Commits

Éric Araujo  committed db60dee

Backport doc improvements for distutils.cmd.Command (#9223).

Original commit by Georg Brandl.

  • Participants
  • Parent commits da76172
  • Branches 2.7

Comments (0)

Files changed (1)

File Doc/distutils/apiref.rst

 In addition, the :mod:`distutils.core` module exposed a number of  classes that
 live elsewhere.
 
-* :class:`Extension` from :mod:`distutils.extension`
-
-* :class:`Command` from :mod:`distutils.cmd`
-
-* :class:`Distribution` from :mod:`distutils.dist`
+* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
+
+* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
+
+* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
 
 A short description of each of these follows, but see the relevant module for
 the full reference.
 ===================================================================
 
 .. 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`.
 
    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.
-
-   The class constructor takes a single argument *dist*, a  :class:`Distribution`
+   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`
    instance.
 
 
-:mod:`distutils.command` --- Individual Distutils commands
-==========================================================
-
-.. module:: distutils.command
-   :synopsis: This subpackage contains one module for each standard Distutils command.
-
-
-.. % \subsubsection{Individual Distutils commands}
-.. % todo
-
-
-:mod:`distutils.command.bdist` --- Build a binary installer
-===========================================================
-
-.. module:: distutils.command.bdist
-   :synopsis: Build a binary installer for a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
-=============================================================================
-
-.. module:: distutils.command.bdist_packager
-   :synopsis: Abstract base class for packagers
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
-================================================================
-
-.. module:: distutils.command.bdist_dumb
-   :synopsis: Build a "dumb" installer - a simple archive of files
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
-=================================================================================
-
-.. module:: distutils.command.bdist_msi
-   :synopsis: Build a binary distribution as a Windows MSI file
-
-.. class:: bdist_msi(Command)
-
-   Builds a `Windows Installer`_ (.msi) binary package.
-
-   .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
-
-   In most cases, the ``bdist_msi`` installer is a better choice than the
-   ``bdist_wininst`` installer, because it provides better support for
-   Win64 platforms, allows administrators to perform non-interactive
-   installations, and allows installation through group policies.
-
-
-:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
-===========================================================================================
-
-.. module:: distutils.command.bdist_rpm
-   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
-====================================================================
-
-.. module:: distutils.command.bdist_wininst
-   :synopsis: Build a Windows installer
-
-
-.. % todo
-
-
-:mod:`distutils.command.sdist` --- Build a source distribution
-==============================================================
-
-.. module:: distutils.command.sdist
-   :synopsis: Build a source distribution
-
-
-.. % todo
-
-
-:mod:`distutils.command.build` --- Build all files of a package
-===============================================================
-
-.. module:: distutils.command.build
-   :synopsis: Build all files of a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_clib` --- Build any C libraries in a package
-==========================================================================
-
-.. module:: distutils.command.build_clib
-   :synopsis: Build any C libraries in a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_ext` --- Build any extensions in a package
-========================================================================
-
-.. module:: distutils.command.build_ext
-   :synopsis: Build any extensions in a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
-===========================================================================
-
-.. module:: distutils.command.build_py
-   :synopsis: Build the .py/.pyc files of a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_scripts` --- Build the scripts of a package
-=========================================================================
-
-.. module:: distutils.command.build_scripts
-   :synopsis: Build the scripts of a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.clean` --- Clean a package build area
-=============================================================
-
-.. module:: distutils.command.clean
-   :synopsis: Clean a package build area
-
-
-.. % todo
-
-
-:mod:`distutils.command.config` --- Perform package configuration
-=================================================================
-
-.. module:: distutils.command.config
-   :synopsis: Perform package configuration
-
-
-.. % todo
-
-
-:mod:`distutils.command.install` --- Install a package
-======================================================
-
-.. module:: distutils.command.install
-   :synopsis: Install a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_data` --- Install data files from a package
-===========================================================================
-
-.. module:: distutils.command.install_data
-   :synopsis: Install data files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
-======================================================================================
-
-.. module:: distutils.command.install_headers
-   :synopsis: Install C/C++ header files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_lib` --- Install library files from a package
-=============================================================================
-
-.. module:: distutils.command.install_lib
-   :synopsis: Install library files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_scripts` --- Install script files from a package
-================================================================================
-
-.. module:: distutils.command.install_scripts
-   :synopsis: Install script files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.register` --- Register a module with the Python Package Index
-=====================================================================================
-
-.. module:: distutils.command.register
-   :synopsis: Register a module with the Python Package Index
-
-
-The ``register`` command registers the package with the Python Package  Index.
-This is described in more detail in :pep:`301`.
-
-.. % 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
+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
+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
+: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
    :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* an unbound method, 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 unbound methods, so they must already have been defined.  The canonical
-example is the :command:`install` command.
+
+.. 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. ``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
+==========================================================
+
+.. module:: distutils.command
+   :synopsis: This subpackage contains one module for each standard Distutils command.
+
+
+.. % \subsubsection{Individual Distutils commands}
+.. % todo
+
+
+:mod:`distutils.command.bdist` --- Build a binary installer
+===========================================================
+
+.. module:: distutils.command.bdist
+   :synopsis: Build a binary installer for a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
+=============================================================================
+
+.. module:: distutils.command.bdist_packager
+   :synopsis: Abstract base class for packagers
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
+================================================================
+
+.. module:: distutils.command.bdist_dumb
+   :synopsis: Build a "dumb" installer - a simple archive of files
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
+=================================================================================
+
+.. module:: distutils.command.bdist_msi
+   :synopsis: Build a binary distribution as a Windows MSI file
+
+.. class:: bdist_msi(Command)
+
+   Builds a `Windows Installer`_ (.msi) binary package.
+
+   .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
+
+   In most cases, the ``bdist_msi`` installer is a better choice than the
+   ``bdist_wininst`` installer, because it provides better support for
+   Win64 platforms, allows administrators to perform non-interactive
+   installations, and allows installation through group policies.
+
+
+:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
+===========================================================================================
+
+.. module:: distutils.command.bdist_rpm
+   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
+====================================================================
+
+.. module:: distutils.command.bdist_wininst
+   :synopsis: Build a Windows installer
+
+
+.. % todo
+
+
+:mod:`distutils.command.sdist` --- Build a source distribution
+==============================================================
+
+.. module:: distutils.command.sdist
+   :synopsis: Build a source distribution
+
+
+.. % todo
+
+
+:mod:`distutils.command.build` --- Build all files of a package
+===============================================================
+
+.. module:: distutils.command.build
+   :synopsis: Build all files of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_clib` --- Build any C libraries in a package
+==========================================================================
+
+.. module:: distutils.command.build_clib
+   :synopsis: Build any C libraries in a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_ext` --- Build any extensions in a package
+========================================================================
+
+.. module:: distutils.command.build_ext
+   :synopsis: Build any extensions in a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
+===========================================================================
+
+.. module:: distutils.command.build_py
+   :synopsis: Build the .py/.pyc files of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_scripts` --- Build the scripts of a package
+=========================================================================
+
+.. module:: distutils.command.build_scripts
+   :synopsis: Build the scripts of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.clean` --- Clean a package build area
+=============================================================
+
+.. module:: distutils.command.clean
+   :synopsis: Clean a package build area
+
+
+.. % todo
+
+
+:mod:`distutils.command.config` --- Perform package configuration
+=================================================================
+
+.. module:: distutils.command.config
+   :synopsis: Perform package configuration
+
+
+.. % todo
+
+
+:mod:`distutils.command.install` --- Install a package
+======================================================
+
+.. module:: distutils.command.install
+   :synopsis: Install a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_data` --- Install data files from a package
+===========================================================================
+
+.. module:: distutils.command.install_data
+   :synopsis: Install data files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
+======================================================================================
+
+.. module:: distutils.command.install_headers
+   :synopsis: Install C/C++ header files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_lib` --- Install library files from a package
+=============================================================================
+
+.. module:: distutils.command.install_lib
+   :synopsis: Install library files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_scripts` --- Install script files from a package
+================================================================================
+
+.. module:: distutils.command.install_scripts
+   :synopsis: Install script files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.register` --- Register a module with the Python Package Index
+=====================================================================================
+
+.. module:: distutils.command.register
+   :synopsis: Register a module with the Python Package Index
+
+
+The ``register`` command registers the package with the Python Package  Index.
+This is described in more detail in :pep:`301`.
+
+.. % todo