[Python-checkins] r76828 - in python/branches/py3k: Doc/distutils/commandref.rst Doc/distutils/sourcedist.rst
tarek.ziade
python-checkins at python.org
Mon Dec 14 00:26:18 CET 2009
Author: tarek.ziade
Date: Mon Dec 14 00:26:18 2009
New Revision: 76828
Log:
Merged revisions 76826 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r76826 | tarek.ziade | 2009-12-14 00:24:13 +0100 (Mon, 14 Dec 2009) | 1 line
reorganized the distutils doc a bit : the MANIFEST.in template system has its own section now. This is easier to find and follow
........
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/distutils/commandref.rst
python/branches/py3k/Doc/distutils/sourcedist.rst
Modified: python/branches/py3k/Doc/distutils/commandref.rst
==============================================================================
--- python/branches/py3k/Doc/distutils/commandref.rst (original)
+++ python/branches/py3k/Doc/distutils/commandref.rst Mon Dec 14 00:26:18 2009
@@ -48,50 +48,6 @@
.. % \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}
Modified: python/branches/py3k/Doc/distutils/sourcedist.rst
==============================================================================
--- python/branches/py3k/Doc/distutils/sourcedist.rst (original)
+++ python/branches/py3k/Doc/distutils/sourcedist.rst Mon Dec 14 00:26:18 2009
@@ -111,9 +111,68 @@
: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 want to force the manifest to be regenerated---for example, if
+you have added or removed files or directories that match an existing pattern in
+the manifest template, you should regenerate the manifest::
+
+ python setup.py sdist --force-manifest
+
+Or, you might just want to (re)generate the manifest, but not create a source
+distribution::
+
+ python setup.py sdist --manifest-only
+
+:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
+shortcut for :option:`--manifest-only`, and :option:`-f` for
+:option:`--force-manifest`.
+
+.. _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, again we turn to the Distutils' own manifest template::
+example, let's look at the Distutils' own manifest template::
include *.txt
recursive-include examples *.txt *.py
@@ -125,9 +184,7 @@
: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.) There are
-several other commands available in the manifest template mini-language; see
-section :ref:`sdist-cmd`.
+:option:`--no-defaults` option to disable the standard set entirely.)
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
@@ -181,44 +238,41 @@
them to the standard representation on your platform. That way, the manifest
template is portable across operating systems.
+Commands
+--------
-.. _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 want to force the manifest to be regenerated---for example, if
-you have added or removed files or directories that match an existing pattern in
-the manifest template, you should regenerate the manifest::
-
- python setup.py sdist --force-manifest
-
-Or, you might just want to (re)generate the manifest, but not create a source
-distribution::
-
- python setup.py sdist --manifest-only
-
-:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
-shortcut for :option:`--manifest-only`, and :option:`-f` for
-:option:`--force-manifest`.
+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.
More information about the Python-checkins
mailing list