reverted distutils doc to its 3.1 state
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index d65c59f..69ec0de 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -21,9 +21,7 @@
.. function:: setup(arguments)
The basic do-everything function that does most everything you could ever ask
- for from a Distutils method.
-
- .. See XXXXX
+ for from a Distutils method. See XXXXX
The setup function takes a large number of arguments. These are laid out in the
following table.
@@ -149,11 +147,11 @@
In addition, the :mod:`distutils.core` module exposed a number of classes that
live elsewhere.
-* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
+* :class:`Extension` from :mod:`distutils.extension`
-* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
+* :class:`Command` from :mod:`distutils.cmd`
-* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
+* :class:`Distribution` from :mod:`distutils.dist`
A short description of each of these follows, but see the relevant module for
the full reference.
@@ -997,7 +995,7 @@
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
true).
-.. XXX Some of this could be replaced with the shutil module?
+**\*\*** Some of this could be replaced with the shutil module? **\*\***
:mod:`distutils.file_util` --- Single file operations
@@ -1313,7 +1311,8 @@
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
command line sets *verbose* to false.
-.. XXX Should be replaced with :mod:`optparse`.
+**\*\*** Should be replaced with :mod:`optik` (which is also now known as
+:mod:`optparse` in Python 2.3 and later). **\*\***
.. function:: fancy_getopt(options, negative_opt, object, args)
@@ -1681,8 +1680,8 @@
===================================================================
.. module:: distutils.cmd
- :synopsis: This module provides the abstract base class Command. This class
- is subclassed by the modules in the distutils.command subpackage.
+ :synopsis: This module provides the abstract base class Command. This class is subclassed
+ by the modules in the distutils.command subpackage.
This module supplies the abstract base class :class:`Command`.
@@ -1692,84 +1691,20 @@
Abstract base class for defining command classes, the "worker bees" of the
Distutils. A useful analogy for command classes is to think of them as
- subroutines with local variables called *options*. The options are declared
- in :meth:`initialize_options` and defined (given their final values) in
- :meth:`finalize_options`, both of which must be defined by every command
- class. The distinction between the two is necessary because option values
- might come from the outside world (command line, config file, ...), and any
- options dependent on other options must be computed after these outside
- influences have been processed --- hence :meth:`finalize_options`. The body
- of the subroutine, where it does all its work based on the values of its
- options, is the :meth:`run` method, which must also be implemented by every
- command class.
+ subroutines with local variables called *options*. The options are declared in
+ :meth:`initialize_options` and defined (given their final values) in
+ :meth:`finalize_options`, both of which must be defined by every command class.
+ The distinction between the two is necessary because option values might come
+ from the outside world (command line, config file, ...), and any options
+ dependent on other options must be computed after these outside influences have
+ been processed --- hence :meth:`finalize_options`. The body of the subroutine,
+ where it does all its work based on the values of its options, is the
+ :meth:`run` method, which must also be implemented by every command class.
- The class constructor takes a single argument *dist*, a :class:`Distribution`
+ The class constructor takes a single argument *dist*, a :class:`Distribution`
instance.
-Creating a new Distutils command
-================================
-
-This section outlines the steps to create a new Distutils command.
-
-A new command lives in a module in the :mod:`distutils.command` package. There
-is a sample template in that directory called :file:`command_template`. Copy
-this file to a new module with the same name as the new command you're
-implementing. This module should implement a class with the same name as the
-module (and the command). So, for instance, to create the command
-``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
-:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
-it so that it's implementing the class :class:`peel_banana`, a subclass of
-:class:`distutils.cmd.Command`.
-
-Subclasses of :class:`Command` must define the following methods.
-
-.. method:: Command.initialize_options()
-
- Set default values for all the options that this command supports. Note that
- these defaults may be overridden by other commands, by the setup script, by
- config files, or by the command-line. Thus, this is not the place to code
- dependencies between options; generally, :meth:`initialize_options`
- implementations are just a bunch of ``self.foo = None`` assignments.
-
-
-.. method:: Command.finalize_options()
-
- Set final values for all the options that this command supports. This is
- always called as late as possible, ie. after any option assignments from the
- command-line or from other commands have been done. Thus, this is the place
- to to code option dependencies: if *foo* depends on *bar*, then it is safe to
- set *foo* from *bar* as long as *foo* still has the same value it was
- assigned in :meth:`initialize_options`.
-
-
-.. method:: Command.run()
-
- A command's raison d'etre: carry out the action it exists to perform,
- controlled by the options initialized in :meth:`initialize_options`,
- customized by other commands, the setup script, the command-line, and config
- files, and finalized in :meth:`finalize_options`. All terminal output and
- filesystem interaction should be done by :meth:`run`.
-
-
-.. attribute:: Command.sub_commands
-
- *sub_commands* formalizes the notion of a "family" of commands,
- e.g. ``install`` as the parent with sub-commands ``install_lib``,
- ``install_headers``, etc. The parent of a family of commands defines
- *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
- predicate)``, with *command_name* a string and *predicate* a function, a
- string or ``None``. *predicate* is a method of the parent command that
- determines whether the corresponding command is applicable in the current
- situation. (E.g. we ``install_headers`` is only applicable if we have any C
- header files to install.) If *predicate* is ``None``, that command is always
- applicable.
-
- *sub_commands* is usually defined at the *end* of a class, because
- predicates can be methods of the class, so they must already have been
- defined. The canonical example is the :command:`install` command.
-
-
:mod:`distutils.command` --- Individual Distutils commands
==========================================================
@@ -2008,3 +1943,76 @@
This is described in more detail in :pep:`301`.
.. % todo
+
+:mod:`distutils.command.check` --- Check the meta-data of a package
+===================================================================
+
+.. module:: distutils.command.check
+ :synopsis: Check the metadata of a package
+
+
+The ``check`` command performs some tests on the meta-data of a package.
+For example, it verifies that all required meta-data are provided as
+the arguments passed to the :func:`setup` function.
+
+.. % todo
+
+
+Creating a new Distutils command
+================================
+
+This section outlines the steps to create a new Distutils command.
+
+A new command lives in a module in the :mod:`distutils.command` package. There
+is a sample template in that directory called :file:`command_template`. Copy
+this file to a new module with the same name as the new command you're
+implementing. This module should implement a class with the same name as the
+module (and the command). So, for instance, to create the command
+``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
+:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
+it so that it's implementing the class :class:`peel_banana`, a subclass of
+:class:`distutils.cmd.Command`.
+
+Subclasses of :class:`Command` must define the following methods.
+
+
+.. method:: Command.initialize_options()
+
+ Set default values for all the options that this command supports. Note that
+ these defaults may be overridden by other commands, by the setup script, by
+ config files, or by the command-line. Thus, this is not the place to code
+ dependencies between options; generally, :meth:`initialize_options`
+ implementations are just a bunch of ``self.foo = None`` assignments.
+
+
+.. method:: Command.finalize_options()
+
+ Set final values for all the options that this command supports. This is
+ always called as late as possible, ie. after any option assignments from the
+ command-line or from other commands have been done. Thus, this is the place
+ to to code option dependencies: if *foo* depends on *bar*, then it is safe to
+ set *foo* from *bar* as long as *foo* still has the same value it was
+ assigned in :meth:`initialize_options`.
+
+
+.. method:: Command.run()
+
+ A command's raison d'etre: carry out the action it exists to perform, controlled
+ by the options initialized in :meth:`initialize_options`, customized by other
+ commands, the setup script, the command-line, and config files, and finalized in
+ :meth:`finalize_options`. All terminal output and filesystem interaction should
+ be done by :meth:`run`.
+
+*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
+as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
+parent of a family of commands defines *sub_commands* as a class attribute; it's
+a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
+and *predicate* a function, a string or None. *predicate* is a method of
+the parent command that determines whether the corresponding command is
+applicable in the current situation. (Eg. we ``install_headers`` is only
+applicable if we have any C header files to install.) If *predicate* is None,
+that command is always applicable.
+
+*sub_commands* is usually defined at the \*end\* of a class, because predicates
+can be methods of the class, so they must already have been defined. The
+canonical example is the :command:`install` command.
diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst
index 8ce94d3..ee06fb4 100644
--- a/Doc/distutils/builtdist.rst
+++ b/Doc/distutils/builtdist.rst
@@ -146,8 +146,8 @@
Creating dumb built distributions
=================================
-.. XXX Need to document absolute vs. prefix-relative packages here, but first
- I have to implement it!
+**\*\*** Need to document absolute vs. prefix-relative packages here, but first
+I have to implement it! **\*\***
.. _creating-rpms:
@@ -241,8 +241,7 @@
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
you distribute or package many Python module distributions, you might want to
put options that apply to all of them in your personal Distutils configuration
-file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable
-this file, you can pass the --no-user-cfg option to setup.py.
+file (:file:`~/.pydistutils.cfg`).
There are three steps to building a binary RPM package, all of which are
handled automatically by the Distutils:
diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst
index 7282961..fbe40de 100644
--- a/Doc/distutils/commandref.rst
+++ b/Doc/distutils/commandref.rst
@@ -48,6 +48,50 @@
.. % \label{clean-cmd}
+.. _sdist-cmd:
+
+Creating a source distribution: the :command:`sdist` command
+============================================================
+
+**\*\*** fragment moved down from above: needs context! **\*\***
+
+The manifest template commands are:
+
++-------------------------------------------+-----------------------------------------------+
+| Command | Description |
++===========================================+===============================================+
+| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
+| | patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
+| | patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
+| ...` | the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
+| ...` | the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
+| | matching --- & any of the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
+| | matching --- & any of the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`prune dir` | exclude all files under *dir* |
++-------------------------------------------+-----------------------------------------------+
+| :command:`graft dir` | include all files under *dir* |
++-------------------------------------------+-----------------------------------------------+
+
+The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
+regular filename characters, ``?`` matches any single regular filename
+character, and ``[range]`` matches any of the characters in *range* (e.g.,
+``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
+character" is platform-specific: on Unix it is anything except slash; on Windows
+anything except backslash or colon.
+
+**\*\*** Windows support not there yet **\*\***
+
.. % \section{Creating a built distribution: the
.. % \protect\command{bdist} command family}
.. % \label{bdist-cmds}
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
index b495928..648063b 100644
--- a/Doc/distutils/examples.rst
+++ b/Doc/distutils/examples.rst
@@ -233,6 +233,58 @@
ext_modules=[Extension('foopkg.foo', ['foo.c'])],
)
+Checking a package
+==================
+
+The ``check`` command allows you to verify if your package meta-data
+meet the minimum requirements to build a distribution.
+
+To run it, just call it using your :file:`setup.py` script. If something is
+missing, ``check`` will display a warning.
+
+Let's take an example with a simple script::
+
+ from distutils.core import setup
+
+ setup(name='foobar')
+
+Running the ``check`` command will display some warnings::
+
+ $ python setup.py check
+ running check
+ warning: check: missing required meta-data: version, url
+ warning: check: missing meta-data: either (author and author_email) or
+ (maintainer and maintainer_email) must be supplied
+
+
+If you use the reStructuredText syntax in the `long_description` field and
+`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
+the syntax is fine with the ``check`` command, using the `restructuredtext`
+option.
+
+For example, if the :file:`setup.py` script is changed like this::
+
+ from distutils.core import setup
+
+ desc = """\
+ My description
+ =============
+
+ This is the description of the ``foobar`` package.
+ """
+
+ setup(name='foobar', version='1', author='tarek',
+ author_email='tarek@ziade.org',
+ url='http://example.com', long_description=desc)
+
+Where the long description is broken, ``check`` will be able to detect it
+by using the `docutils` parser::
+
+ $ pythontrunk setup.py check --restructuredtext
+ running check
+ warning: check: Title underline too short. (line 2)
+ warning: check: Could not finish the parsing.
+
.. % \section{Multiple extension modules}
.. % \label{multiple-ext}
diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst
index 5a70d03..972ff02 100644
--- a/Doc/distutils/extending.rst
+++ b/Doc/distutils/extending.rst
@@ -15,8 +15,8 @@
should be copied into packages in addition to :file:`.py` files as a
convenience.
-Most distutils command implementations are subclasses of the
-:class:`distutils.cmd.Command` class. New commands may directly inherit from
+Most distutils command implementations are subclasses of the :class:`Command`
+class from :mod:`distutils.cmd`. New commands may directly inherit from
:class:`Command`, while replacements often derive from :class:`Command`
indirectly, directly subclassing the command they are replacing. Commands are
required to derive from :class:`Command`.
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 9208e36..5ec94c7 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -207,7 +207,7 @@
SWIG on the interface file and compile the resulting C/C++ file into your
extension.
-.. XXX SWIG support is rough around the edges and largely untested!
+**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
This warning notwithstanding, options to SWIG can be currently passed like
this::
@@ -326,7 +326,7 @@
(Again, this sort of non-portable construct should be avoided if you intend to
distribute your code.)
-.. XXX Should mention clib libraries here or somewhere else!
+**\*\*** Should mention clib libraries here or somewhere else! **\*\***
Other options
diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst
index 2cfdf69..96e891b 100644
--- a/Doc/distutils/sourcedist.rst
+++ b/Doc/distutils/sourcedist.rst
@@ -26,16 +26,16 @@
+===========+=========================+=========+
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
+-----------+-------------------------+---------+
-| ``gztar`` | gzip'ed tar file | \(2) |
+| ``gztar`` | gzip'ed tar file | (2),(4) |
| | (:file:`.tar.gz`) | |
+-----------+-------------------------+---------+
-| ``bztar`` | bzip2'ed tar file | |
+| ``bztar`` | bzip2'ed tar file | \(4) |
| | (:file:`.tar.bz2`) | |
+-----------+-------------------------+---------+
| ``ztar`` | compressed tar file | \(4) |
| | (:file:`.tar.Z`) | |
+-----------+-------------------------+---------+
-| ``tar`` | tar file (:file:`.tar`) | |
+| ``tar`` | tar file (:file:`.tar`) | \(4) |
+-----------+-------------------------+---------+
Notes:
@@ -51,16 +51,8 @@
of the standard Python library since Python 1.6)
(4)
- requires the :program:`compress` program. Notice that this format is now
- pending for deprecation and will be removed in the future versions of Python.
-
-When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or
-``tar``) under Unix, you can specify the ``owner`` and ``group`` names
-that will be set for each member of the archive.
-
-For example, if you want all files of the archive to be owned by root::
-
- python setup.py sdist --owner=root --group=root
+ requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
+ :program:`bzip2`, or :program:`compress`
.. _manifest:
@@ -76,10 +68,10 @@
:option:`packages` options
* all C source files mentioned in the :option:`ext_modules` or
- :option:`libraries` options
+ :option:`libraries` options (
- .. XXX Getting C library sources is currently broken -- no
- :meth:`get_source_files` method in :file:`build_clib.py`!
+ **\*\*** getting C library sources currently broken---no
+ :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
* scripts identified by the :option:`scripts` option
See :ref:`distutils-installing-scripts`.
@@ -111,60 +103,9 @@
:file:`MANIFEST`, you must specify everything: the default set of files
described above does not apply in this case.
-See :ref:`manifest_template` section for a syntax reference.
-
-.. _manifest-options:
-
-Manifest-related options
-========================
-
-The normal course of operations for the :command:`sdist` command is as follows:
-
-* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
- and create the manifest
-
-* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
- with just the default file set
-
-* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
- recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
- :file:`MANIFEST.in`
-
-* use the list of files now in :file:`MANIFEST` (either just generated or read
- in) to create the source distribution archive(s)
-
-There are a couple of options that modify this behaviour. First, use the
-:option:`--no-defaults` and :option:`--no-prune` to disable the standard
-"include" and "exclude" sets.
-
-Second, you might just want to (re)generate the manifest, but not create a
-source distribution::
-
- python setup.py sdist --manifest-only
-
-:option:`-o` is a sortcut for :option:`--manifest-only`.
-
-.. _manifest_template:
-
-The MANIFEST.in template
-========================
-
-A :file:`MANIFEST.in` file can be added in a project to define the list of
-files to include in the distribution built by the :command:`sdist` command.
-
-When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
-and interpret it to generate the :file:`MANIFEST` file that contains the
-list of files that will be included in the package.
-
-This mechanism can be used when the default list of files is not enough.
-(See :ref:`manifest`).
-
-Principle
----------
-
The manifest template has one command per line, where each command specifies a
set of files to include or exclude from the source distribution. For an
-example, let's look at the Distutils' own manifest template::
+example, again we turn to the Distutils' own manifest template::
include *.txt
recursive-include examples *.txt *.py
@@ -176,7 +117,9 @@
:file:`examples/sample?/build`. All of this is done *after* the standard
include set, so you can exclude files from the standard set with explicit
instructions in the manifest template. (Or, you can use the
-:option:`--no-defaults` option to disable the standard set entirely.)
+:option:`--no-defaults` option to disable the standard set entirely.) There are
+several other commands available in the manifest template mini-language; see
+section :ref:`sdist-cmd`.
The order of commands in the manifest template matters: initially, we have the
list of default files as described above, and each command in the template adds
@@ -230,41 +173,36 @@
them to the standard representation on your platform. That way, the manifest
template is portable across operating systems.
-Commands
---------
-The manifest template commands are:
+.. _manifest-options:
-+-------------------------------------------+-----------------------------------------------+
-| Command | Description |
-+===========================================+===============================================+
-| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
-| | patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
-| | patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
-| ...` | the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
-| ...` | the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
-| | matching --- & any of the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
-| | matching --- & any of the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`prune dir` | exclude all files under *dir* |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`graft dir` | include all files under *dir* |
-+-------------------------------------------+-----------------------------------------------+
+Manifest-related options
+========================
-The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
-regular filename characters, ``?`` matches any single regular filename
-character, and ``[range]`` matches any of the characters in *range* (e.g.,
-``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
-character" is platform-specific: on Unix it is anything except slash; on Windows
-anything except backslash or colon.
+The normal course of operations for the :command:`sdist` command is as follows:
+
+* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
+ and create the manifest
+
+* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
+ with just the default file set
+
+* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
+ recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
+ :file:`MANIFEST.in`
+
+* use the list of files now in :file:`MANIFEST` (either just generated or read
+ in) to create the source distribution archive(s)
+
+There are a couple of options that modify this behaviour. First, use the
+:option:`--no-defaults` and :option:`--no-prune` to disable the standard
+"include" and "exclude" sets.
+
+Second, you might just want to (re)generate the manifest, but not create a source
+distribution::
+
+ python setup.py sdist --manifest-only
+
+:option:`-o` is a shortcut for :option:`--manifest-only`.
+
diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
index 7b790b1..e947245 100644
--- a/Doc/distutils/uploading.rst
+++ b/Doc/distutils/uploading.rst
@@ -60,13 +60,13 @@
setup(name='Distutils',
long_description=open('README.txt'))
-In that case, :file:`README.txt` is a regular reStructuredText text file located
-in the root of the package besides :file:`setup.py`.
+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 :mod:`docutils` package
+: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
-:mod:`docutils` will display a warning if there's something wrong with your syntax.
+`docutils` will display a warning if there's something wrong with your syntax.