more info on long_description

Doc/distutils/setupscript.rst

@@ -576,7 +576,7 @@ This information includes:
 |                      | description of the        |                 |        |
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
-| ``long_description`` | longer description of the | long string     |        |
+| ``long_description`` | longer description of the | long string     | \(5)   |
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
 | ``download_url``     | location where the        | URL             | \(4)   |
@@ -603,6 +603,10 @@ Notes:
     versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
     <http://pypi.python.org/pypi>`_.
 
+(5)
+    The ``long_description`` field is used by PyPI when you are registering a
+    package, to build its home page.
+
 'short string'
     A single line of text, not more than 200 characters.
 
@@ -686,5 +690,3 @@ failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
 to anything except an empty string, and distutils will now print detailed
 information what it is doing, and prints the full traceback in case an exception
 occurs.
-
-

Doc/distutils/uploading.rst

@@ -43,3 +43,32 @@ Other :command:`upload` options include :option:`--repository=<url>` or
 *section* the name of the section in :file:`$HOME/.pypirc`, and
 :option:`--show-response` (which displays the full response text from the PyPI
 server for help in debugging upload problems).
+
+PyPI package display
+====================
+
+The ``long_description`` field plays a special role at PyPI. It is used by
+the server to display a home page for the registered package.
+
+If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
+syntax for this field, PyPI will parse it and display an HTML output for
+the package home page.
+
+The ``long_description`` field can be attached to a text file located
+in the package::
+
+    from distutils.core import setup
+
+    setup(name='Distutils',
+          long_description=open('README.txt'))
+
+In that case, `README.txt` is a regular reStructuredText text file located
+in the root of the package besides `setup.py`.
+
+To prevent registering broken reStructuredText content, you can use the
+:program:`rst2html` program that is provided by the `docutils` package
+and check the ``long_description`` from the command line::
+
+    $ python setup.py --long-description | rst2html.py > output.html
+
+`docutils` will display a warning if there's something wrong with your syntax.