Merge "docs: Use sphinx-apidoc library for autodoc generation"

This commit is contained in:
Zuul 2018-11-22 02:21:47 +00:00 committed by Gerrit Code Review
commit 7293f0ee81
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

@ -153,7 +153,4 @@ This example must be read as ``<allowed_role_1> and <allowed_role_2> and not
Implementation
--------------
.. automodule:: patrole_tempest_plugin.requirements_authority
:members:
:undoc-members:
:special-members:
:py:mod:`Requirements Authority Module <patrole_tempest_plugin.requirements_authority>`

View File

@ -61,7 +61,7 @@ Framework
---------
.. toctree::
:maxdepth: 2
:maxdepth: 3
framework/overview
framework/rbac_validation
@ -69,6 +69,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