Fixes documentation building

- Adds the ability to build docs using tox
 - Fixes autodoc generation

A Sphinx extension is introduced in the commit to facilitate building
the API documentation. This extension should be removed when
bug 1260495 is fixed.

Change-Id: Ibf5e5403cb7d3e67947c87b2828b64a56a11fc30
This commit is contained in:
David Stanek 2013-10-21 14:10:27 +00:00
parent 35242b04eb
commit 3f27b309f0
9 changed files with 75 additions and 13 deletions

2
.gitignore vendored
View File

@ -16,8 +16,8 @@ pep8.txt
nosetests.xml
doc/build
.DS_Store
doc/source/api
doc/source/modules.rst
doc/source/keystone.*
ChangeLog
AUTHORS
build/

View File

@ -4,6 +4,6 @@ Building Docs
Developer documentation is generated using Sphinx. To build this documentation,
run the following from the root of the repository::
$ python setup.py build_sphinx
$ tox -e docs
The documentation will be built at ``doc/build/``.

0
doc/ext/__init__.py Normal file
View File

48
doc/ext/apidoc.py Normal file
View File

@ -0,0 +1,48 @@
# vim: tabstop=4 shiftwidth=4 softtabstop=4
# Copyright 2013 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
# NOTE(dstanek): Uncomment the [pbr] section in setup.cfg and remove this
# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.
import functools
import os.path as path
from sphinx import apidoc
# NOTE(dstanek): pbr will run Sphinx multiple times when it generates
# documentation. Once for each builder. To run this extension we use the
# 'builder-inited' hook that fires at the begining of a Sphinx build.
# We use ``run_already`` to make sure apidocs are only generated once
# even if Sphinx is run multiple times.
run_already = False
def run_apidoc(app):
global run_already
if run_already:
return
run_already = True
package_dir = path.abspath(path.join(app.srcdir, '..', '..', 'keystone'))
source_dir = path.join(app.srcdir, 'api')
apidoc.main(['apidoc', package_dir, '-f',
'-H', 'Keystone Modules',
'-o', source_dir])
def setup(app):
app.connect('builder-inited', run_apidoc)

View File

@ -18,7 +18,11 @@ import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('..')) # NOTE(dstanek): path for our
# Sphinx extension
# NOTE(dstanek): adds _ to the builtins so keystone modules can be imported
__builtins__['_'] = str
# -- General configuration ----------------------------------------------------
@ -31,7 +35,12 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'oslo.sphinx',
# NOTE(dstanek): Uncomment the [pbr] section in setup.cfg and
# remove this Sphinx extension when
# https://launchpad.net/bugs/1260495 is fixed.
'ext.apidoc',
]
todo_include_todos = True

View File

@ -364,13 +364,8 @@ Example (using the above cacheable_function)::
Building the Documentation
==========================
The documentation is all generated with Sphinx from within the docs directory.
To generate the full set of HTML documentation::
The documentation is generated with Sphinx uning the tox command. To create HTML docs and man pages::
cd docs
make autodoc
make html
make man
$ tox -e docs
the results are in the docs/build/html and docs/build/man directories
respectively.
The results are in the docs/build/html and docs/build/man directories respectively.

View File

@ -75,7 +75,7 @@ Code Documentation
.. toctree::
:maxdepth: 1
api/autoindex
api/modules
Indices and tables
==================

View File

@ -55,3 +55,9 @@ mapping_file = babel.cfg
output_file = keystone/locale/keystone.pot
copyright_holder = OpenStack Foundation
msgid_bugs_address = https://bugs.launchpad.net/keystone
# NOTE(dstanek): Uncomment the [pbr] section below and remove the ext.apidoc
# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.
#[pbr]
#autodoc_tree_index_modules = True
#autodoc_tree_root = ./keystone

View File

@ -1,7 +1,7 @@
[tox]
minversion = 1.6
skipsdist = True
envlist = py26,py27,py33,pep8
envlist = py26,py27,py33,pep8,docs
[testenv]
usedevelop = True
@ -41,3 +41,7 @@ ignore = H803
builtins = _
exclude=.venv,.git,.tox,build,dist,doc,*openstack/common*,*lib/python*,*egg,tools,vendor,.update-venv,*.ini
[testenv:docs]
commands=
python setup.py build_sphinx