Merged revisions 70007 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r70007 | tarek.ziade | 2009-02-27 03:14:35 +0100 (Fri, 27 Feb 2009) | 1 line

  more info on long_description
........

Doc/distutils/setupscript.rst

@@ -314,7 +314,7 @@ For example, if you need to link against libraries known to be in the standard
 library search path on target systems ::
 
     Extension(...,
-             libraries=['_gdbm', 'readline'])
+              libraries=['gdbm', 'readline'])
 
 If you need to link with libraries in a non-standard location, you'll have to
 include the location in ``library_dirs``::
@@ -575,7 +575,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)   |
@@ -602,6 +602,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.
 
@@ -683,5 +687,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

@@ -41,3 +41,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.