docs: Use sphinx-apidoc library for autodoc generation

This package is used for automatic generation of autodoc
documentation which offers the following advantages:

* the Patrole framework for all modules is always built
  and kept up to date
* it is isolated in its own page layout
* it can still be linked to by other documentation pages
  easily

Change-Id: I101557efe47293f88ee65b99275fdc8424c02e35
This commit is contained in:
Felipe Monteiro 2018-11-05 17:15:30 +00:00
parent d771e34d24
commit 47c43cb6ca
10 changed files with 32 additions and 23 deletions

1
.gitignore vendored
View File

@ -45,6 +45,7 @@ output/*/index.html
# Sphinx
doc/build
doc/source/_static/patrole.conf.sample
doc/source/framework/code/
# pbr generates these
AUTHORS

View File

@ -4,3 +4,4 @@
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
openstackdocstheme>=1.18.1 # Apache-2.0
reno>=2.5.0 # Apache-2.0
sphinxcontrib-apidoc>=0.2.0 # BSD

View File

@ -15,7 +15,13 @@
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
# 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('../'))
sys.path.insert(0, os.path.abspath('./'))
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
@ -26,8 +32,23 @@ extensions = [
'sphinx.ext.viewcode',
'openstackdocstheme',
'oslo_config.sphinxconfiggen',
'sphinxcontrib.apidoc',
]
# sphinxcontrib.apidoc options
apidoc_module_dir = '../../patrole_tempest_plugin'
apidoc_output_dir = 'framework/code'
apidoc_excluded_paths = [
'hacking',
'hacking/*',
'tests',
'tests/*',
'config.py',
'plugin.py',
'version.py'
]
apidoc_separate_modules = True
config_generator_config_file = '../../etc/config-generator.patrole.conf'
sample_config_basename = '_static/patrole'

View File

@ -57,7 +57,4 @@ This validation approach should be used when:
Implementation
--------------
.. automodule:: patrole_tempest_plugin.policy_authority
:members:
:undoc-members:
:special-members:
:py:mod:`Policy Authority Module <patrole_tempest_plugin.policy_authority>`

View File

@ -32,7 +32,4 @@ requirements-driven approach to validating RBAC in Patrole.
Implementation
--------------
.. automodule:: patrole_tempest_plugin.rbac_authority
:members:
:undoc-members:
:special-members:
:py:mod:`RBAC Authority Module <patrole_tempest_plugin.rbac_authority>`

View File

@ -26,10 +26,7 @@ custom policy rule definitions, which can be arbitrarily complex.
Implementation
--------------
.. automodule:: patrole_tempest_plugin.rbac_utils
:members:
:private-members:
:special-members:
:py:mod:`RBAC Utils Module <patrole_tempest_plugin.rbac_utils>`
.. _Tempest credentials: https://docs.openstack.org/tempest/latest/library/credential_providers.html
.. _dynamic credentials: https://docs.openstack.org/tempest/latest/configuration.html#dynamic-credentials

View File

@ -14,7 +14,4 @@ policy name defined by the ``service``).
Implementation
--------------
.. automodule:: patrole_tempest_plugin.rbac_rule_validation
:members:
:private-members:
:special-members:
:py:mod:`RBAC Rule Validation Module <patrole_tempest_plugin.rbac_rule_validation>`

View File

@ -100,7 +100,4 @@ allowed_role = the ``oslo.policy`` role that is allowed to perform the API.
Implementation
--------------
.. automodule:: patrole_tempest_plugin.requirements_authority
:members:
:undoc-members:
:special-members:
:py:mod:`Requirements Authority Module <patrole_tempest_plugin.requirements_authority>`

View File

@ -60,7 +60,7 @@ Framework
---------
.. toctree::
:maxdepth: 2
:maxdepth: 3
framework/overview
framework/rbac_validation
@ -68,6 +68,7 @@ Framework
framework/policy_authority
framework/requirements_authority
framework/rbac_utils
framework/code/modules
Indices and tables
==================

View File

@ -60,7 +60,7 @@ deps =
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands =
rm -rf doc/build
rm -rf doc/build doc/source/framework/code
sphinx-build -W -b html doc/source doc/build/html
whitelist_externals = rm