diff options
author | Matt Riedemann <mriedem@us.ibm.com> | 2015-07-08 07:35:20 -0700 |
---|---|---|
committer | Matt Riedemann <mriedem@us.ibm.com> | 2015-07-08 08:13:40 -0700 |
commit | 07292c2d8437ca3e10669038d1036f6903e54c80 (patch) | |
tree | 3917bcd5cce8dce67b4bc8f298579fd316ad63f3 | |
parent | c5cc43a5beacb7c1d3e147f3654fdea207e8340a (diff) | |
download | pbr-07292c2d8437ca3e10669038d1036f6903e54c80.tar.gz |
Add more documentation around building docs
After digging in pbr and sphinx source code for a day to figure out
what I was doing wrong, let's update the pbr docs with respect to
building docs using the autodoc features in pbr.
Specifically, document the autodoc_tree_excludes and warnerrors
options and point out that you will probably need to set the
exclude_patterns options in your sphinx config when excluding
modules from the docs build and warnerrors=True. Also provide
some links to the Sphinx docs for more details.
Related-Bug: #1260495
Related-Bug: #1472276
Change-Id: Ib43830d08a156f37a3763ad2807d5c1f4cdbe3fe
-rw-r--r-- | doc/source/index.rst | 25 |
1 files changed, 23 insertions, 2 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index b9e49eb..ac746d7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -95,6 +95,8 @@ Sphinx documentation setups are altered to generate man pages by default. They also have several pieces of information that are known to setup.py injected into the sphinx config. +See the pbr_ section for details on configuring your project for autodoc. + Requirements ------------ @@ -296,8 +298,12 @@ pbr --- The pbr section controls pbr specific options and behaviours. -The `autodoc_tree_index_modules` is a boolean value controlling whether pbr -should generate an index of modules using `sphinx-apidoc`. +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 <http://sphinx-doc.org/man/sphinx-apidoc.html>`_ +for more information. The `autodoc_index_modules` is a boolean option controlling whether pbr should itself generates documentation for Python modules of the project. By default, @@ -305,6 +311,21 @@ 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. +The `warnerrors` boolean option is used to tell Sphinx builders to treat +warnings as errors which will cause sphinx-build to fail if it encounters +warnings. This is generally useful to ensure your documentation stays clean +once you have a good docs build. + +.. note:: + + When using `autodoc_tree_excludes` or `autodoc_index_modules` you may also + need to set `exclude_patterns` in your Sphinx configuration file (generally + found at doc/source/conf.py in most OpenStack projects) otherwise + Sphinx may complain about documents that are not in a toctree. This is + especially true if the `warnerrors=True` option is set. See + http://sphinx-doc.org/config.html for more information on configuring + Sphinx. + Comments -------- |