docs: Use definition lists

These are far more concise and easier to read.

Change-Id: I411685b6e7d5385386b40cbf4b8bd4445b3c6847
This commit is contained in:
Stephen Finucane 2017-04-12 11:20:02 +01:00
parent 5da68b9894
commit 54fb6e71b7
1 changed files with 65 additions and 46 deletions

View File

@ -217,12 +217,12 @@ itself)::
pbr.config.drivers =
plain = pbr.cfg.driver:Plain
pbr provides its own section in these documents, ostensibly called `pbr`, and
provides a custom version of Sphinx's `build_sphinx` section. Most other
`pbr` provides its own section in these documents, ostensibly called ``pbr``,
and provides a custom version of Sphinx's ``build_sphinx`` section. Most other
sections are provided by setuptools and may influence either the build itself
or the output of various `setuptools commands`__. The remaining sections are
provided by libraries that provide setuptools extensions, such as
`extract_mesages` (provided by `Babel`__). Some of these are described below.
``extract_mesages`` (provided by `Babel`__). Some of these are described below.
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
__ http://babel.pocoo.org/en/latest/setup.html
@ -250,57 +250,76 @@ The ``files`` section defines the install location of files in the package
using three fundamental keys: ``packages``, ``namespace_packages``, and
``data_files``.
``packages`` is a list of top-level packages that should be installed. The
behavior of packages is similar to ``setuptools.find_packages`` in that it
recurses the python package hierarchy below the given top level and installs
all of it. If ``packages`` is not specified, it defaults to the value of the
``name`` field given in the ``[metadata]`` section.
``packages``
``namespace_packages`` is the same, but is a list of packages that provide
namespace packages.
A list of top-level packages that should be installed. The behavior of
packages is similar to ``setuptools.find_packages`` in that it recurses the
python package hierarchy below the given top level and installs all of it. If
``packages`` is not specified, it defaults to the value of the ``name`` field
given in the ``[metadata]`` section.
``data_files`` lists files to be installed. The format is an indented block
that contains key value pairs which specify target directory and source file
to install there. More than one source file for a directory may be indicated
with a further indented list. Source files are stripped of leading directories.
Additionally, `pbr` supports a simple file globbing syntax for installing
entire directory structures, thus::
``namespace_packages``
[files]
data_files =
etc/pbr = etc/pbr/*
etc/neutron =
etc/api-paste.ini
etc/dhcp-agent.ini
etc/init.d = neutron.init
Similar to ``packages``, but is a list of packages that provide namespace
packages.
will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
both of which pbr will expect to find in the `etc` directory in the root of
the source tree. Additionally, `neutron.init` from that dir will be installed
in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
the source tree will be installed into `/etc/pbr`.
``data_files``
Note that this behavior is relative to the effective root of the environment
into which the packages are installed, so depending on available permissions
this could be the actual system-wide `/etc` directory or just a top-level `etc`
subdirectory of a virtualenv.
A list of files to be installed. The format is an indented block that
contains key value pairs which specify target directory and source file to
install there. More than one source file for a directory may be indicated
with a further indented list. Source files are stripped of leading
directories. Additionally, `pbr` supports a simple file globbing syntax for
installing entire directory structures, thus::
[files]
data_files =
etc/pbr = etc/pbr/*
etc/neutron =
etc/api-paste.ini
etc/dhcp-agent.ini
etc/init.d = neutron.init
will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
both of which pbr will expect to find in the `etc` directory in the root of
the source tree. Additionally, `neutron.init` from that dir will be installed
in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
the source tree will be installed into `/etc/pbr`.
Note that this behavior is relative to the effective root of the environment
into which the packages are installed, so depending on available permissions
this could be the actual system-wide `/etc` directory or just a top-level
`etc` subdirectory of a virtualenv.
pbr
~~~
The ``pbr`` section controls pbr specific options and behaviours.
The ``pbr`` section controls `pbr` specific options and behaviours.
The ``autodoc_tree_index_modules`` is a boolean option controlling whether pbr
should generate an index of modules using ``sphinx-apidoc``. By default,
`setup.py` is excluded. The list of excluded modules can be specified with the
``autodoc_tree_excludes`` option. See the `sphinx-apidoc man page`_ for more
information.
``autodoc_tree_index_modules``
The ``autodoc_index_modules`` is a boolean option controlling whether `pbr`
should itself generates documentation for Python modules of the project. By
default, all found Python modules are included; some of them can be excluded
by listing them in ``autodoc_exclude_modules``. This list of modules can
contains `fnmatch` style pattern (e.g. `myapp.tests.*`) to exclude some modules.
A boolean option controlling whether `pbr` should generate an index of
modules using `sphinx-apidoc`. By default, all files except `setup.py` are
included, but this can be overridden using the ``autodoc_tree_excludes``
option.
``autodoc_tree_excludes``
A list of modules to exclude when building documentation using
`sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man
page`_ for more information.
``autodoc_index_modules``
A boolean option controlling whether `pbr` should itself generates
documentation for Python modules of the project. By default, all found Python
modules are included; some of them can be excluded by listing them in
``autodoc_exclude_modules``.
``autodoc_exclude_modules``
A list of modules to exclude when building module documentation using `pbr`.
`fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
.. note::
@ -448,11 +467,11 @@ environment, you can use::
Testing
-------
pbr overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py
test``). The following sequence is followed:
`pbr` overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py test``). The
following sequence is followed:
#. If a ``.testr.conf`` file exists and `testrepository
<https://pypi.python.org/pypi/testrepository>`__ is installed, PBR
<https://pypi.python.org/pypi/testrepository>`__ is installed, `pbr`
will use it as the test runner. See the ``testr`` documentation
for more details.