started a tutorial

2 files changed, 134 insertions, 1 deletions

diff --git a/docs/source/index.rst b/docs/source/index.rst
index c2026a5..541b260 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -42,12 +42,15 @@ Distutils2 group (GSoC students, mentors, volunteers).
 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 @@ The documentation is split in three sections, as in the standard Python docs:
 
    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
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
+
+
+
+