[Python-checkins] cpython (merge 3.3 -> default): Issue #16406: Combine the doc pages for uploading and registering to PyPI.
chris.jerdonek
python-checkins at python.org
Wed Feb 27 19:05:42 CET 2013
http://hg.python.org/cpython/rev/44ebac378e51
changeset: 82420:44ebac378e51
parent: 82416:e0f3dcd30af8
parent: 82419:58a28aa70fec
user: Chris Jerdonek <chris.jerdonek at gmail.com>
date: Wed Feb 27 10:04:23 2013 -0800
summary:
Issue #16406: Combine the doc pages for uploading and registering to PyPI.
files:
Doc/distutils/index.rst | 1 -
Doc/distutils/packageindex.rst | 121 +++++++++++++++++++-
Doc/distutils/setupscript.rst | 5 +-
Doc/distutils/uploading.rst | 77 +-------------
Misc/NEWS | 2 +
5 files changed, 122 insertions(+), 84 deletions(-)
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -22,7 +22,6 @@
sourcedist.rst
builtdist.rst
packageindex.rst
- uploading.rst
examples.rst
extending.rst
commandref.rst
diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst
--- a/Doc/distutils/packageindex.rst
+++ b/Doc/distutils/packageindex.rst
@@ -1,12 +1,33 @@
+.. index::
+ single: Python Package Index (PyPI)
+ single: PyPI; (see Python Package Index (PyPI))
+
.. _package-index:
-**********************************
-Registering with the Package Index
-**********************************
+*******************************
+The Python Package Index (PyPI)
+*******************************
-The Python Package Index (PyPI) holds meta-data describing distributions
-packaged with distutils. The distutils command :command:`register` is used to
-submit your distribution's meta-data to the index. It is invoked as follows::
+The `Python Package Index (PyPI)`_ holds :ref:`meta-data <meta-data>`
+describing distributions packaged with distutils, as well as package data like
+distribution files if the package author wishes.
+
+Distutils exposes two commands for submitting package data to PyPI: the
+:ref:`register <package-register>` command for submitting meta-data to PyPI
+and the :ref:`upload <package-upload>` command for submitting distribution
+files. Both commands read configuration data from a special file called the
+:ref:`.pypirc file <pypirc>`. PyPI :ref:`displays a home page
+<package-display>` for each package created from the ``long_description``
+submitted by the :command:`register` command.
+
+
+.. _package-register:
+
+Registering Packages
+====================
+
+The distutils command :command:`register` is used to submit your distribution's
+meta-data to the index. It is invoked as follows::
python setup.py register
@@ -48,6 +69,52 @@
versions to display and hide.
+.. _package-upload:
+
+Uploading Packages
+==================
+
+The distutils command :command:`upload` pushes the distribution files to PyPI.
+
+The command is invoked immediately after building one or more distribution
+files. For example, the command ::
+
+ python setup.py sdist bdist_wininst upload
+
+will cause the source distribution and the Windows installer to be uploaded to
+PyPI. Note that these will be uploaded even if they are built using an earlier
+invocation of :file:`setup.py`, but that only distributions named on the command
+line for the invocation including the :command:`upload` command are uploaded.
+
+The :command:`upload` command uses the username, password, and repository URL
+from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
+file). If a :command:`register` command was previously called in the same command,
+and if the password was entered in the prompt, :command:`upload` will reuse the
+entered password. This is useful if you do not want to store a clear text
+password in the :file:`$HOME/.pypirc` file.
+
+You can specify another PyPI server with the ``--repository=url`` option::
+
+ python setup.py sdist bdist_wininst upload -r http://example.com/pypi
+
+See section :ref:`pypirc` for more on defining several servers.
+
+You can use the ``--sign`` option to tell :command:`upload` to sign each
+uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
+be available for execution on the system :envvar:`PATH`. You can also specify
+which key to use for signing using the ``--identity=name`` option.
+
+Other :command:`upload` options include ``--repository=url`` or
+``--repository=section`` where *url* is the url of the server and
+*section* the name of the section in :file:`$HOME/.pypirc`, and
+``--show-response`` (which displays the full response text from the PyPI
+server for help in debugging upload problems).
+
+
+.. index::
+ single: .pypirc file
+ single: Python Package Index (PyPI); .pypirc file
+
.. _pypirc:
The .pypirc file
@@ -102,3 +169,45 @@
may also be used::
python setup.py register -r other
+
+
+.. _package-display:
+
+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
+
+ with open('README.txt') as file:
+ long_description = file.read()
+
+ setup(name='Distutils',
+ long_description=long_description)
+
+In that case, :file:`README.txt` is a regular reStructuredText text file located
+in the root of the package besides :file:`setup.py`.
+
+To prevent registering broken reStructuredText content, you can use the
+:program:`rst2html` program that is provided by the :mod:`docutils` package and
+check the ``long_description`` from the command line::
+
+ $ python setup.py --long-description | rst2html.py > output.html
+
+:mod:`docutils` will display a warning if there's something wrong with your
+syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
+to ``rst2html.py`` in the command above), being able to run the command above
+without warnings does not guarantee that PyPI will convert the content
+successfully.
+
+
+.. _Python Package Index (PyPI): http://pypi.python.org/
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -610,8 +610,9 @@
<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.
+ The ``long_description`` field is used by PyPI when you are
+ :ref:`registering <package-register>` a package, to
+ :ref:`build its home page <package-display>`.
(6)
The ``license`` field is a text indicating the license covering the
diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
--- a/Doc/distutils/uploading.rst
+++ b/Doc/distutils/uploading.rst
@@ -1,80 +1,7 @@
-.. _package-upload:
+:orphan:
***************************************
Uploading Packages to the Package Index
***************************************
-The Python Package Index (PyPI) not only stores the package info, but also the
-package data if the author of the package wishes to. The distutils command
-:command:`upload` pushes the distribution files to PyPI.
-
-The command is invoked immediately after building one or more distribution
-files. For example, the command ::
-
- python setup.py sdist bdist_wininst upload
-
-will cause the source distribution and the Windows installer to be uploaded to
-PyPI. Note that these will be uploaded even if they are built using an earlier
-invocation of :file:`setup.py`, but that only distributions named on the command
-line for the invocation including the :command:`upload` command are uploaded.
-
-The :command:`upload` command uses the username, password, and repository URL
-from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
-file). If a :command:`register` command was previously called in the same command,
-and if the password was entered in the prompt, :command:`upload` will reuse the
-entered password. This is useful if you do not want to store a clear text
-password in the :file:`$HOME/.pypirc` file.
-
-You can specify another PyPI server with the ``--repository=url`` option::
-
- python setup.py sdist bdist_wininst upload -r http://example.com/pypi
-
-See section :ref:`pypirc` for more on defining several servers.
-
-You can use the ``--sign`` option to tell :command:`upload` to sign each
-uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
-be available for execution on the system :envvar:`PATH`. You can also specify
-which key to use for signing using the ``--identity=name`` option.
-
-Other :command:`upload` options include ``--repository=url`` or
-``--repository=section`` where *url* is the url of the server and
-*section* the name of the section in :file:`$HOME/.pypirc`, and
-``--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
-
- with open('README.txt') as file:
- long_description = file.read()
-
- setup(name='Distutils',
- long_description=long_description)
-
-In that case, :file:`README.txt` is a regular reStructuredText text file located
-in the root of the package besides :file:`setup.py`.
-
-To prevent registering broken reStructuredText content, you can use the
-:program:`rst2html` program that is provided by the :mod:`docutils` package and
-check the ``long_description`` from the command line::
-
- $ python setup.py --long-description | rst2html.py > output.html
-
-:mod:`docutils` will display a warning if there's something wrong with your
-syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
-to ``rst2html.py`` in the command above), being able to run the command above
-without warnings does not guarantee that PyPI will convert the content
-successfully.
-
+The contents of this page have moved to the section :ref:`package-index`.
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -1036,6 +1036,8 @@
Documentation
-------------
+- Issue #16406: Combine the pages for uploading and registering to PyPI.
+
- Issue #16403: Document how distutils uses the maintainer field in
PKG-INFO. Patch by Jyrki Pulliainen.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list