[Python-checkins] distutils2: started a tutorial
tarek.ziade
python-checkins at python.org
Fri Oct 8 22:21:24 CEST 2010
tarek.ziade pushed b3c21fc3d270 to distutils2:
http://hg.python.org/distutils2/rev/b3c21fc3d270
changeset: 757:b3c21fc3d270
tag: tip
user: Tarek Ziade <tarek at ziade.org>
date: Fri Oct 08 22:21:07 2010 +0200
summary: started a tutorial
files: docs/source/index.rst, docs/source/tutorial.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -42,12 +42,15 @@
Please remember that this is a work in progress. The documentation is not
complete, not spell-checked, and uses different styles.
-The documentation is split in three sections, as in the standard Python docs:
+The documentation is split in four sections, as in the standard Python docs:
:doc:`install/index`
A guide for for end-users wanting to install a Python application or
library.
+:doc:`tutorial`
+ A tutorial for Python developers to discover Distutils2 main features.
+
:doc:`distutils/index`
A guide for Python developers wanting to package and distribute their
project.
@@ -65,6 +68,7 @@
devresources
install/index
+ tutorial
distutils/index
library/distutils2
library/pkgutil
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
new file mode 100644
--- /dev/null
+++ b/docs/source/tutorial.rst
@@ -0,0 +1,129 @@
+===================
+Distutils2 tutorial
+===================
+
+Welcome to the Distutils2 tutorial ! We will learn here how to use Distutils2
+to package your project.
+
+
+Installing Distutils2
+=====================
+
+Quite simple, my dear reader::
+
+ $ pip install Distutils2
+
+Or.. grab it at PyPI and run::
+
+ $ python setup.py install
+
+
+
+Getting started
+===============
+
+Distutils2 works with the *setup.cfg* file. It contains all the metadata for
+your project, as defined in PEP 345, but also declare what your project
+contains.
+
+Let's say you have a project called *CLVault* containing one package called
+*clvault*,and a few scripts insde. You can use the *mkcfg* script to create
+a *setup.cfg* file for the project. The script will ask you a few questions::
+
+ $ mkdir CLVault
+ $ cd CLVault
+ $ python -m distutils2.mkcfg
+ Project name [CLVault]:
+ Current version number: 0.1
+ Package description:
+ >Command-line utility to store and retrieve passwords
+ Author name: Tarek Ziade
+ Author e-mail address: tarek at ziade.org
+ Project Home Page: http://bitbucket.org/tarek/clvault
+ Do you want to add a package ? (y/n): y
+ Package name: clvault
+ Do you want to add a package ? (y/n): n
+ Do you want to set Trove classifiers? (y/n): y
+ Please select the project status:
+
+ 1 - Planning
+ 2 - Pre-Alpha
+ 3 - Alpha
+ 4 - Beta
+ 5 - Production/Stable
+ 6 - Mature
+ 7 - Inactive
+
+ Status: 3
+ What license do you use: GPL
+ Matching licenses:
+
+ 1) License :: OSI Approved :: GNU General Public License (GPL)
+ 2) License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
+
+ Type the number of the license you wish to use or ? to try again:: 1
+ Do you want to set other trove identifiers (y/n) [n]: n
+ Wrote "setup.cfg".
+
+
+A setup.cfg file is created, containing the metadata of your project and the
+list of the packages it contains::
+
+ $ more setup.cfg
+ [metadata]
+ name = CLVault
+ version = 0.1
+ author = Tarek Ziade
+ author_email = tarek at ziade.org
+ description = Command-line utility to store and retrieve passwords
+ home_page = http://bitbucket.org/tarek/clvault
+
+ classifier = Development Status :: 3 - Alpha
+ License :: OSI Approved :: GNU General Public License (GPL)
+
+ [files]
+
+ packages = clvault
+
+
+Our project will depend on the *keyring* project. Let's add it in the
+[metadata] section::
+
+ [metadata]
+ ...
+ requires_dist =
+ keyring
+
+
+
+Running commands
+================
+
+You can run useful commands on your project once the setup.cfg file is ready:
+
+- sdist: creates a source distribution
+- register: register your project to PyPI
+- upload: upload the distribution to PyPI
+- install: install it
+
+All commands are run using the run script::
+
+ $ python -m distutils2.run install
+ $ python -m distutils2.run sdist
+ $ python -m distutils2.run upload
+
+If you want to push a source distribution of your project at PyPI, do::
+
+ $ python -m distutils2.run sdist register upload
+
+
+Installing the project
+======================
+
+People will have to manually run the distutils2 install command::
+
+ $ python -m distutils2.run install
+
+
+
+
--
Repository URL: http://hg.python.org/distutils2
More information about the Python-checkins
mailing list