1 files changed, 129 insertions, 0 deletions
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
new file mode 100644
index 0000000..d3bf089
--- /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@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@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
+
+
+
+