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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 88c1bea..45d8021 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -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 @@
'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'
diff --git a/doc/source/framework/policy_authority.rst b/doc/source/framework/policy_authority.rst
index 37b698c..f039692 100644
--- a/doc/source/framework/policy_authority.rst
+++ b/doc/source/framework/policy_authority.rst
@@ -57,7 +57,4 @@
Implementation
--------------
-.. automodule:: patrole_tempest_plugin.policy_authority
- :members:
- :undoc-members:
- :special-members:
+:py:mod:`Policy Authority Module <patrole_tempest_plugin.policy_authority>`
diff --git a/doc/source/framework/rbac_authority.rst b/doc/source/framework/rbac_authority.rst
index 40f2a8d..7ffe24f 100644
--- a/doc/source/framework/rbac_authority.rst
+++ b/doc/source/framework/rbac_authority.rst
@@ -32,7 +32,4 @@
Implementation
--------------
-.. automodule:: patrole_tempest_plugin.rbac_authority
- :members:
- :undoc-members:
- :special-members:
+:py:mod:`RBAC Authority Module <patrole_tempest_plugin.rbac_authority>`
diff --git a/doc/source/framework/rbac_utils.rst b/doc/source/framework/rbac_utils.rst
index b13a4a3..f7cb182 100644
--- a/doc/source/framework/rbac_utils.rst
+++ b/doc/source/framework/rbac_utils.rst
@@ -26,10 +26,7 @@
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
diff --git a/doc/source/framework/rbac_validation.rst b/doc/source/framework/rbac_validation.rst
index 6cd1534..460c08c 100644
--- a/doc/source/framework/rbac_validation.rst
+++ b/doc/source/framework/rbac_validation.rst
@@ -14,7 +14,4 @@
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>`
diff --git a/doc/source/framework/requirements_authority.rst b/doc/source/framework/requirements_authority.rst
index 628f0c0..dec6267 100644
--- a/doc/source/framework/requirements_authority.rst
+++ b/doc/source/framework/requirements_authority.rst
@@ -100,7 +100,4 @@
Implementation
--------------
-.. automodule:: patrole_tempest_plugin.requirements_authority
- :members:
- :undoc-members:
- :special-members:
+:py:mod:`Requirements Authority Module <patrole_tempest_plugin.requirements_authority>`
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c03aac6..8837f2e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -60,7 +60,7 @@
---------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
framework/overview
framework/rbac_validation
@@ -68,6 +68,7 @@
framework/policy_authority
framework/requirements_authority
framework/rbac_utils
+ framework/code/modules
Indices and tables
==================