summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
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)
commit55729fe7189ab3d21c14cc6be6896ca4f0ebad65 (patch)
tree7a1f161ff45f5036b848c47556d2c979379cfcdf
parent8c86ecdab52528ed7457872c99252d0df94c7157 (diff)
downloadcpython-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.rst10
-rw-r--r--Doc/install/index.rst56
-rw-r--r--Doc/library/distutils.rst15
-rw-r--r--Doc/tools/sphinxext/indexcontent.html4
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 &amp; 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/>