[Python-checkins] distutils2: docs updated

[tarek.ziade]

tarek.ziade pushed dc5fbc82c929 to distutils2:

http://hg.python.org/distutils2/rev/dc5fbc82c929
changeset:   261:dc5fbc82c929
user:        Konrad Delong <konryd at gmail.com>
date:        Sun May 09 14:10:36 2010 -0400
summary:     docs updated
files:       docs/source/index.rst, docs/source/new_commands.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -12,6 +12,7 @@
    :maxdepth: 2
 
    metadata
+   new_commands
 
 Indices and tables
 ==================
diff --git a/docs/source/new_commands.rst b/docs/source/new_commands.rst
new file mode 100644
--- /dev/null
+++ b/docs/source/new_commands.rst
@@ -0,0 +1,64 @@
+========
+Commands
+========
+
+Distutils2 provides a set of commands that are not present in distutils itself.
+You might recognize some of them from other projects, like Distribute or
+Setuptools.
+
+``upload_docs`` - Upload package documentation to PyPI
+======================================================
+
+PyPI now supports uploading project documentation to the dedicated URL
+http://packages.python.org/<project>/.
+
+The ``upload_docs`` command will create the necessary zip file out of a
+documentation directory and will post to the repository.
+
+Note that to upload the documentation of a project, the corresponding version
+must already be registered with PyPI, using the distutils ``register``
+command -- just like the ``upload`` command.
+
+Assuming there is an ``Example`` project with documentation in the
+subdirectory ``docs``, e.g.::
+
+  Example/
+  |-- example.py
+  |-- setup.cfg
+  |-- setup.py
+  |-- docs
+  |   |-- build
+  |   |   `-- html
+  |   |   |   |-- index.html
+  |   |   |   `-- tips_tricks.html
+  |   |-- conf.py
+  |   |-- index.txt
+  |   `-- tips_tricks.txt
+
+You can simply pass the documentation directory path to the ``upload_docs``
+command::
+
+    python setup.py upload_docs --upload-dir=docs/build/html
+
+As with any other ``setuptools`` based command, you can define useful
+defaults in the ``setup.cfg`` of your Python project, e.g.:
+
+.. code-block:: ini
+
+    [upload_docs]
+    upload-dir = docs/build/html
+
+The ``upload_docs`` command has the following options:
+
+``--upload-dir``
+    The directory to be uploaded to the repository.
+
+``--show-response``
+    Display the full response text from server; this is useful for debugging
+    PyPI problems.
+
+``--repository=URL, -r URL``
+    The URL of the repository to upload to.  Defaults to
+    http://pypi.python.org/pypi (i.e., the main PyPI installation).
+
+

--
Repository URL: http://hg.python.org/distutils2