diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst index 5fa25a6d58a..b3a52317699 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 00000000000..58b78350e73 --- /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 f1a0f6b915b..53a69aecd7c 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 10f9d266ef8..778346ff38c 100644 --- a/Doc/tools/sphinxext/indexcontent.html +++ b/Doc/tools/sphinxext/indexcontent.html @@ -21,9 +21,9 @@ + finding and installing modules and applications

+ packaging and distributing modules and applications