Doc: remove invalid uses of ":option:" which will emit warnings in Sphinx 1.3.
This commit is contained in:
Georg Brandl
parent
8a97896a76
commit
3f40c40dea
|
|
@ -186,21 +186,21 @@ Distutils configuration files. Various options and sections in the
|
|||
+------------------------------------------+----------------------------------------------+
|
||||
| RPM :file:`.spec` file option or section | Distutils setup script option |
|
||||
+==========================================+==============================================+
|
||||
| Name | :option:`name` |
|
||||
| Name | ``name`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Summary (in preamble) | :option:`description` |
|
||||
| Summary (in preamble) | ``description`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Version | :option:`version` |
|
||||
| Version | ``version`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Vendor | :option:`author` and :option:`author_email`, |
|
||||
| | or --- & :option:`maintainer` and |
|
||||
| | :option:`maintainer_email` |
|
||||
| Vendor | ``author`` and ``author_email``, |
|
||||
| | or --- & ``maintainer`` and |
|
||||
| | ``maintainer_email`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Copyright | :option:`license` |
|
||||
| Copyright | ``license`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Url | :option:`url` |
|
||||
| Url | ``url`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| %description (section) | :option:`long_description` |
|
||||
| %description (section) | ``long_description`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
|
||||
Additionally, there are many options in :file:`.spec` files that don't have
|
||||
|
|
@ -211,27 +211,27 @@ options to the :command:`bdist_rpm` command as follows:
|
|||
| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value |
|
||||
| or section | | |
|
||||
+===============================+=============================+=========================+
|
||||
| Release | :option:`release` | "1" |
|
||||
| Release | ``release`` | "1" |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Group | :option:`group` | "Development/Libraries" |
|
||||
| Group | ``group`` | "Development/Libraries" |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Vendor | :option:`vendor` | (see above) |
|
||||
| Vendor | ``vendor`` | (see above) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Packager | :option:`packager` | (none) |
|
||||
| Packager | ``packager`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Provides | :option:`provides` | (none) |
|
||||
| Provides | ``provides`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Requires | :option:`requires` | (none) |
|
||||
| Requires | ``requires`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Conflicts | :option:`conflicts` | (none) |
|
||||
| Conflicts | ``conflicts`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Obsoletes | :option:`obsoletes` | (none) |
|
||||
| Obsoletes | ``obsoletes`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Distribution | :option:`distribution_name` | (none) |
|
||||
| Distribution | ``distribution_name`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| BuildRequires | :option:`build_requires` | (none) |
|
||||
| BuildRequires | ``build_requires`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Icon | :option:`icon` | (none) |
|
||||
| Icon | ``icon`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
|
||||
Obviously, supplying even a few of these options on the command-line would be
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ universal :option:`--help` option, e.g. ::
|
|||
[...]
|
||||
|
||||
Note that an option spelled :option:`--foo-bar` on the command-line is spelled
|
||||
:option:`foo_bar` in configuration files.
|
||||
``foo_bar`` in configuration files.
|
||||
|
||||
.. _distutils-build-ext-inplace:
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ own :file:`setup.cfg`::
|
|||
doc/
|
||||
examples/
|
||||
|
||||
Note that the :option:`doc_files` option is simply a whitespace-separated string
|
||||
Note that the ``doc_files`` option is simply a whitespace-separated string
|
||||
split across multiple lines for readability.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Pure Python distribution (by module)
|
|||
|
||||
If you're just distributing a couple of modules, especially if they don't live
|
||||
in a particular package, you can specify them individually using the
|
||||
:option:`py_modules` option in the setup script.
|
||||
``py_modules`` option in the setup script.
|
||||
|
||||
In the simplest case, you'll have two files to worry about: a setup script and
|
||||
the single module you're distributing, :file:`foo.py` in this example::
|
||||
|
|
@ -41,12 +41,12 @@ directory.) A minimal setup script to describe this situation would be::
|
|||
)
|
||||
|
||||
Note that the name of the distribution is specified independently with the
|
||||
:option:`name` option, and there's no rule that says it has to be the same as
|
||||
``name`` option, and there's no rule that says it has to be the same as
|
||||
the name of the sole module in the distribution (although that's probably a good
|
||||
convention to follow). However, the distribution name is used to generate
|
||||
filenames, so you should stick to letters, digits, underscores, and hyphens.
|
||||
|
||||
Since :option:`py_modules` is a list, you can of course specify multiple
|
||||
Since ``py_modules`` is a list, you can of course specify multiple
|
||||
modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
|
||||
setup might look like this::
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ requires the least work to describe in your setup script::
|
|||
)
|
||||
|
||||
If you want to put modules in directories not named for their package, then you
|
||||
need to use the :option:`package_dir` option again. For example, if the
|
||||
need to use the ``package_dir`` option again. For example, if the
|
||||
:file:`src` directory holds modules in the :mod:`foobar` package::
|
||||
|
||||
<root>/
|
||||
|
|
@ -169,8 +169,8 @@ in which case your setup script would be ::
|
|||
|
||||
(The empty string also stands for the current directory.)
|
||||
|
||||
If you have sub-packages, they must be explicitly listed in :option:`packages`,
|
||||
but any entries in :option:`package_dir` automatically extend to sub-packages.
|
||||
If you have sub-packages, they must be explicitly listed in ``packages``,
|
||||
but any entries in ``package_dir`` automatically extend to sub-packages.
|
||||
(In other words, the Distutils does *not* scan your source tree, trying to
|
||||
figure out which directories correspond to Python packages by looking for
|
||||
:file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
|
||||
|
|
@ -199,8 +199,8 @@ then the corresponding setup script would be ::
|
|||
Single extension module
|
||||
=======================
|
||||
|
||||
Extension modules are specified using the :option:`ext_modules` option.
|
||||
:option:`package_dir` has no effect on where extension source files are found;
|
||||
Extension modules are specified using the ``ext_modules`` option.
|
||||
``package_dir`` has no effect on where extension source files are found;
|
||||
it only affects the source for pure Python modules. The simplest case, a
|
||||
single extension module in a single C source file, is::
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ commands to be added which can support existing :file:`setup.py` scripts without
|
|||
requiring modifications to the Python installation. This is expected to allow
|
||||
third-party extensions to provide support for additional packaging systems, but
|
||||
the commands can be used for anything distutils commands can be used for. A new
|
||||
configuration option, :option:`command_packages` (command-line option
|
||||
configuration option, ``command_packages`` (command-line option
|
||||
:option:`--command-packages`), can be used to specify additional packages to be
|
||||
searched for modules implementing commands. Like all distutils options, this
|
||||
can be specified on the command line or in a configuration file. This option
|
||||
|
|
@ -75,7 +75,7 @@ This new option can be used to add any number of packages to the list of
|
|||
packages searched for command implementations; multiple package names should be
|
||||
separated by commas. When not specified, the search is only performed in the
|
||||
:mod:`distutils.command` package. When :file:`setup.py` is run with the option
|
||||
:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages
|
||||
``--command-packages distcmds,buildcmds``, however, the packages
|
||||
:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
|
||||
in that order. New commands are expected to be implemented in modules of the
|
||||
same name as the command by classes sharing the same name. Given the example
|
||||
|
|
|
|||
|
|
@ -62,9 +62,9 @@ code instead of hardcoding path separators::
|
|||
Listing whole packages
|
||||
======================
|
||||
|
||||
The :option:`packages` option tells the Distutils to process (build, distribute,
|
||||
The ``packages`` option tells the Distutils to process (build, distribute,
|
||||
install, etc.) all pure Python modules found in each package mentioned in the
|
||||
:option:`packages` list. In order to do this, of course, there has to be a
|
||||
``packages`` list. In order to do this, of course, there has to be a
|
||||
correspondence between package names and directories in the filesystem. The
|
||||
default correspondence is the most obvious one, i.e. package :mod:`distutils` is
|
||||
found in the directory :file:`distutils` relative to the distribution root.
|
||||
|
|
@ -75,7 +75,7 @@ the directory where your setup script lives. If you break this promise, the
|
|||
Distutils will issue a warning but still process the broken package anyway.
|
||||
|
||||
If you use a different convention to lay out your source directory, that's no
|
||||
problem: you just have to supply the :option:`package_dir` option to tell the
|
||||
problem: you just have to supply the ``package_dir`` option to tell the
|
||||
Distutils about your convention. For example, say you keep all Python source
|
||||
under :file:`lib`, so that modules in the "root package" (i.e., not in any
|
||||
package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
|
||||
|
|
@ -94,13 +94,13 @@ written in the setup script as ::
|
|||
|
||||
package_dir = {'foo': 'lib'}
|
||||
|
||||
A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
|
||||
A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
|
||||
applies to all packages below *package*, so the :mod:`foo.bar` case is
|
||||
automatically handled here. In this example, having ``packages = ['foo',
|
||||
'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
|
||||
:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir`
|
||||
:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir``
|
||||
applies recursively, you must explicitly list all packages in
|
||||
:option:`packages`: the Distutils will *not* recursively scan your source tree
|
||||
``packages``: the Distutils will *not* recursively scan your source tree
|
||||
looking for any directory with an :file:`__init__.py` file.)
|
||||
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ This describes two modules, one of them in the "root" package, the other in the
|
|||
:mod:`pkg` package. Again, the default package/directory layout implies that
|
||||
these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
|
||||
that :file:`pkg/__init__.py` exists as well. And again, you can override the
|
||||
package/directory correspondence using the :option:`package_dir` option.
|
||||
package/directory correspondence using the ``package_dir`` option.
|
||||
|
||||
|
||||
.. _describing-extensions:
|
||||
|
|
@ -138,7 +138,7 @@ directories, libraries to link with, etc.).
|
|||
.. XXX read over this section
|
||||
|
||||
All of this is done through another keyword argument to :func:`setup`, the
|
||||
:option:`ext_modules` option. :option:`ext_modules` is just a list of
|
||||
``ext_modules`` option. ``ext_modules`` is just a list of
|
||||
:class:`~distutils.core.Extension` instances, each of which describes a
|
||||
single extension module.
|
||||
Suppose your distribution includes a single extension, called :mod:`foo` and
|
||||
|
|
@ -181,7 +181,7 @@ in the filesystem (and therefore where in Python's namespace hierarchy) the
|
|||
resulting extension lives.
|
||||
|
||||
If you have a number of extensions all in the same package (or all under the
|
||||
same base package), use the :option:`ext_package` keyword argument to
|
||||
same base package), use the ``ext_package`` keyword argument to
|
||||
:func:`setup`. For example, ::
|
||||
|
||||
setup(...,
|
||||
|
|
@ -336,24 +336,24 @@ Other options
|
|||
|
||||
There are still some other options which can be used to handle special cases.
|
||||
|
||||
The :option:`optional` option is a boolean; if it is true,
|
||||
The ``optional`` option is a boolean; if it is true,
|
||||
a build failure in the extension will not abort the build process, but
|
||||
instead simply not install the failing extension.
|
||||
|
||||
The :option:`extra_objects` option is a list of object files to be passed to the
|
||||
The ``extra_objects`` option is a list of object files to be passed to the
|
||||
linker. These files must not have extensions, as the default extension for the
|
||||
compiler is used.
|
||||
|
||||
:option:`extra_compile_args` and :option:`extra_link_args` can be used to
|
||||
``extra_compile_args`` and ``extra_link_args`` can be used to
|
||||
specify additional command line options for the respective compiler and linker
|
||||
command lines.
|
||||
|
||||
:option:`export_symbols` is only useful on Windows. It can contain a list of
|
||||
``export_symbols`` is only useful on Windows. It can contain a list of
|
||||
symbols (functions or variables) to be exported. This option is not needed when
|
||||
building compiled extensions: Distutils will automatically add ``initmodule``
|
||||
to the list of exported symbols.
|
||||
|
||||
The :option:`depends` option is a list of files that the extension depends on
|
||||
The ``depends`` option is a list of files that the extension depends on
|
||||
(for example header files). The build command will call the compiler on the
|
||||
sources to rebuild extension if any on this files has been modified since the
|
||||
previous build.
|
||||
|
|
@ -449,7 +449,7 @@ to refer to the current interpreter location. By default, it is replaced with
|
|||
the current interpreter location. The :option:`--executable` (or :option:`-e`)
|
||||
option will allow the interpreter path to be explicitly overridden.
|
||||
|
||||
The :option:`scripts` option simply is a list of files to be handled in this
|
||||
The ``scripts`` option simply is a list of files to be handled in this
|
||||
way. From the PyXML setup script::
|
||||
|
||||
setup(...,
|
||||
|
|
@ -514,11 +514,11 @@ The corresponding call to :func:`setup` might be::
|
|||
Installing Additional Files
|
||||
===========================
|
||||
|
||||
The :option:`data_files` option can be used to specify additional files needed
|
||||
The ``data_files`` option can be used to specify additional files needed
|
||||
by the module distribution: configuration files, message catalogs, data files,
|
||||
anything which doesn't fit in the previous categories.
|
||||
|
||||
:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
|
||||
``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
|
||||
following way::
|
||||
|
||||
setup(...,
|
||||
|
|
@ -539,7 +539,7 @@ modules). Each file name in *files* is interpreted relative to the
|
|||
directory information from *files* is used to determine the final location of
|
||||
the installed file; only the name of the file is used.
|
||||
|
||||
You can specify the :option:`data_files` options as a simple sequence of files
|
||||
You can specify the ``data_files`` options as a simple sequence of files
|
||||
without specifying a target directory, but this is not recommended, and the
|
||||
:command:`install` command will print a warning in this case. To install data
|
||||
files directly in the target directory, an empty string should be given as the
|
||||
|
|
@ -650,7 +650,7 @@ information is sometimes used to indicate sub-releases. These are
|
|||
1.0.1a2
|
||||
the second alpha release of the first patch version of 1.0
|
||||
|
||||
:option:`classifiers` are specified in a Python list::
|
||||
``classifiers`` are specified in a Python list::
|
||||
|
||||
setup(...,
|
||||
classifiers=[
|
||||
|
|
|
|||
|
|
@ -72,16 +72,16 @@ If you don't supply an explicit list of files (or instructions on how to
|
|||
generate one), the :command:`sdist` command puts a minimal default set into the
|
||||
source distribution:
|
||||
|
||||
* all Python source files implied by the :option:`py_modules` and
|
||||
:option:`packages` options
|
||||
* all Python source files implied by the ``py_modules`` and
|
||||
``packages`` options
|
||||
|
||||
* all C source files mentioned in the :option:`ext_modules` or
|
||||
:option:`libraries` options
|
||||
* all C source files mentioned in the ``ext_modules`` or
|
||||
``libraries`` options
|
||||
|
||||
.. XXX getting C library sources currently broken---no
|
||||
:meth:`get_source_files` method in :file:`build_clib.py`!
|
||||
|
||||
* scripts identified by the :option:`scripts` option
|
||||
* scripts identified by the ``scripts`` option
|
||||
See :ref:`distutils-installing-scripts`.
|
||||
|
||||
* anything that looks like a test script: :file:`test/test\*.py` (currently, the
|
||||
|
|
@ -167,7 +167,7 @@ source distribution:
|
|||
|
||||
#. include all Python source files in the :file:`distutils` and
|
||||
:file:`distutils/command` subdirectories (because packages corresponding to
|
||||
those two directories were mentioned in the :option:`packages` option in the
|
||||
those two directories were mentioned in the ``packages`` option in the
|
||||
setup script---see section :ref:`setup-script`)
|
||||
|
||||
#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
|
||||
|
|
|
|||
|
|
@ -555,7 +555,7 @@ will include metadata, making it possible to build automated cataloguing systems
|
|||
and experiment with them. With the result experience, perhaps it'll be possible
|
||||
to design a really good catalog and then build support for it into Python 2.2.
|
||||
For example, the Distutils :command:`sdist` and :command:`bdist_\*` commands
|
||||
could support a :option:`upload` option that would automatically upload your
|
||||
could support a ``upload`` option that would automatically upload your
|
||||
package to a catalog server.
|
||||
|
||||
You can start creating packages containing :file:`PKG-INFO` even if you're not
|
||||
|
|
|
|||
Loading…
Reference in New Issue