merge heads.

1 files changed, 112 insertions, 0 deletions

diff --git a/Doc/packaging/tutorial.rst b/Doc/packaging/tutorial.rst
new file mode 100644
index 0000000..04f41e5
--- /dev/null
+++ b/Doc/packaging/tutorial.rst
@@ -0,0 +1,112 @@
+==================
+Packaging tutorial
+==================
+
+Welcome to the Packaging tutorial! We will learn how to use Packaging
+to package your project.
+
+.. TODO merge with introduction.rst
+
+
+Getting started
+---------------
+
+Packaging 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 inside. You can use the *pysetup* script to create
+a *setup.cfg* file for the project. The script will ask you a few questions::
+
+   $ mkdir CLVault
+   $ cd CLVault
+   $ pysetup create
+   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@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::
+
+   $ cat setup.cfg
+   [metadata]
+   name = CLVault
+   version = 0.1
+   author = Tarek Ziade
+   author_email = tarek@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_dist: install it
+
+All commands are run using the run script::
+
+   $ pysetup run install_dist
+   $ pysetup run sdist
+   $ pysetup run upload
+
+If you want to push a source distribution of your project to PyPI, do::
+
+   $ pysetup run sdist register upload
+
+
+Installing the project
+----------------------
+
+The project can be installed by manually running the packaging install command::
+
+   $ pysetup run install_dist