diff options
author | Éric Araujo <merwok@netwok.org> | 2011-06-02 13:45:25 (GMT) |
---|---|---|
committer | Éric Araujo <merwok@netwok.org> | 2011-06-02 13:45:25 (GMT) |
commit | 55729fe7189ab3d21c14cc6be6896ca4f0ebad65 (patch) | |
tree | 7a1f161ff45f5036b848c47556d2c979379cfcdf | |
parent | 8c86ecdab52528ed7457872c99252d0df94c7157 (diff) | |
download | cpython-55729fe7189ab3d21c14cc6be6896ca4f0ebad65.zip cpython-55729fe7189ab3d21c14cc6be6896ca4f0ebad65.tar.gz cpython-55729fe7189ab3d21c14cc6be6896ca4f0ebad65.tar.bz2 |
Packaging doc: Add missing index file, improve main page description.
Also promote notices from distutils doc to deprecation boxes.
-rw-r--r-- | Doc/distutils/index.rst | 10 | ||||
-rw-r--r-- | Doc/install/index.rst | 56 | ||||
-rw-r--r-- | Doc/library/distutils.rst | 15 | ||||
-rw-r--r-- | Doc/tools/sphinxext/indexcontent.html | 4 |
4 files changed, 71 insertions, 14 deletions
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst index 5fa25a6..b3a5231 100644 --- a/Doc/distutils/index.rst +++ b/Doc/distutils/index.rst @@ -14,6 +14,10 @@ the module developer's point of view, describing how to use the Distutils to make Python modules and extensions easily available to a wider audience with very little overhead for build/release/install mechanics. +.. deprecated:: 3.3 + :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and + :ref:`packaging-install-index`. + .. toctree:: :maxdepth: 2 :numbered: @@ -36,9 +40,3 @@ following the above guidelines: .. toctree:: install.rst - - -.. seealso:: - - :ref:`packaging-index` and :ref:`packaging-install-index` - Documentation of Packaging, the new version of Distutils. diff --git a/Doc/install/index.rst b/Doc/install/index.rst new file mode 100644 index 0000000..58b7835 --- /dev/null +++ b/Doc/install/index.rst @@ -0,0 +1,56 @@ +.. _packaging-install-index: + +****************************** + Installing Python Projects +****************************** + +:Author: Greg Ward and Packaging contributors +:Release: |version| +:Date: |today| + +.. TODO: Fill in XXX comments + +.. The audience for this document includes people who don't know anything + about Python and aren't about to learn the language just in order to + install and maintain it for their users, i.e. system administrators. + Thus, I have to be sure to explain the basics at some point: + sys.path and PYTHONPATH at least. Should probably give pointers to + other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. + + Finally, it might be useful to include all the material from my "Care + and Feeding of a Python Installation" talk in here somewhere. Yow! + +.. topic:: Abstract + + This document describes Packaging from the end-user's point of view: it + explains how to extend the functionality of a standard Python installation by + building and installing third-party Python modules and applications. + + +This guide is split into a simple overview followed by a longer presentation of +the :program:`pysetup` script, the Python package management tool used to +build, distribute, search for, install, remove and list Python distributions. + +.. TODO integrate install and pysetup instead of duplicating + +.. toctree:: + :maxdepth: 2 + :numbered: + + install + pysetup + pysetup-config + pysetup-servers + + +.. seealso:: + + :ref:`packaging-index` + The manual for developers of Python projects who want to package and + distribute them. This describes how to use :mod:`packaging` to make + projects easily found and added to an existing Python installation. + + :mod:`packaging` + A library reference for developers of packaging tools wanting to use + standalone building blocks like :mod:`~packaging.version` or + :mod:`~packaging.metadata`, or extend Packaging itself. diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst index f1a0f6b..53a69ae 100644 --- a/Doc/library/distutils.rst +++ b/Doc/library/distutils.rst @@ -12,21 +12,24 @@ additional modules into a Python installation. The new modules may be either 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C. -This package is discussed in two separate chapters: +.. deprecated:: 3.3 + :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and + :ref:`packaging-install-index`. +User documentation and API reference are provided in another document: + .. seealso:: :ref:`distutils-index` The manual for developers and packagers of Python modules. This describes how to prepare :mod:`distutils`\ -based packages so that they may be - easily installed into an existing Python installation. + easily installed into an existing Python installation. If also contains + instructions for end-users wanting to install a distutils-based package, + :ref:`install-index`. - :ref:`install-index` - An "administrators" manual which includes information on installing - modules into an existing Python installation. You do not need to be a - Python programmer to read this manual. +.. trick to silence a Sphinx warning .. toctree:: :hidden: diff --git a/Doc/tools/sphinxext/indexcontent.html b/Doc/tools/sphinxext/indexcontent.html index 10f9d26..778346f 100644 --- a/Doc/tools/sphinxext/indexcontent.html +++ b/Doc/tools/sphinxext/indexcontent.html @@ -21,9 +21,9 @@ <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/> <span class="linkdescr">reference for C/C++ programmers</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Projects</a><br/> - <span class="linkdescr">information for installers & sys-admins</span></p> + <span class="linkdescr">finding and installing modules and applications</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("packaging/index") }}">Distributing Python Projects</a><br/> - <span class="linkdescr">sharing modules with others</span></p> + <span class="linkdescr">packaging and distributing modules and applications</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/> <span class="linkdescr">guide for documentation authors</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/> |