From 07292c2d8437ca3e10669038d1036f6903e54c80 Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Wed, 8 Jul 2015 07:35:20 -0700 Subject: 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 --- doc/source/index.rst | 25 +++++++++++++++++++++++-- 1 file 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 `_ +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 -------- -- cgit v1.2.1