diff options
author | Jenkins <jenkins@review.openstack.org> | 2017-04-14 06:25:13 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2017-04-14 06:25:13 +0000 |
commit | 5da68b9894b13416d6e559a3063509f958d9efa7 (patch) | |
tree | 06e5356a0015b20a9c9695babbeb282102630a6d | |
parent | 84a85991339328a188f181385ec4386eb97206dc (diff) | |
parent | b9c9630966161c5c69e33475d681f405fae41ff0 (diff) | |
download | pbr-5da68b9894b13416d6e559a3063509f958d9efa7.tar.gz |
Merge "doc: Document Sphinx integration"
-rw-r--r-- | doc/source/index.rst | 66 |
1 files changed, 60 insertions, 6 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index d3afd6a..65be4e2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -201,6 +201,7 @@ itself):: keywords = setup distutils + [files] packages = pbr @@ -209,18 +210,19 @@ itself):: etc/init = pbr.packaging.conf pbr.version.conf + [entry_points] console_scripts = pbr = pbr.cmd:main pbr.config.drivers = plain = pbr.cfg.driver:Plain -pbr provides its own section in these documents, ostensibly called `pbr`. 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`__) or `sphinx_build` (provided by -`Sphinx`__). Some of these are described below. +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. __ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference __ http://babel.pocoo.org/en/latest/setup.html @@ -310,6 +312,58 @@ contains `fnmatch` style pattern (e.g. `myapp.tests.*`) to exclude some modules. set. See the `Sphinx build configuration file`_ documentation for more information on configuring Sphinx. +.. versionchanged:: 2.0 + + The ``pbr`` section used to take a ``warnerrors`` option that would enable + the ``-W`` (Turn warnings into errors.) option when building Sphinx. This + feature was broken in 1.10 and was removed in pbr 2.0 in favour of the + ``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+. + +build_sphinx +~~~~~~~~~~~~ + +The ``build_sphinx`` section is a version of the ``build_sphinx`` setuptools +plugin provided with Sphinx. This plugin extends the original plugin to add the +following: + +- Automatic generation of module documentation using the apidoc__ tool + +- Automatic configuration of the `project`, `version` and `release` settings + using information from `pbr` itself + +- Support for multiple builders using the ``builders`` configuration option + + .. note:: + + Sphinx 1.6 adds support for multiple builders using the default `builder` + option. You should refer to this file for more information. + +The version of ``build_sphinx`` provided by `pbr` provides a single additional +option. + +``builders`` + + A space or comma separated list of builders to run. For example, to build + both HTML and man page documentation, you would define the following in your + `setup.cfg`: + + .. code-block:: ini + + [build_sphinx] + builders = html,man + source-dir = doc/source + build-dir = doc/build + all-files = 1 + +For information on the remaining options, refer to the `Sphinx +documentation`__. In addition, the ``autodoc_index_modules``, +``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and +``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output +of the automatic module documentation generation. + +__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html +__ http://www.sphinx-doc.org/en/stable/setuptools.html + entry_points ~~~~~~~~~~~~ |