Cleanup doc support
Cleanup docs building: - Remove obsolete sections from setup.cfg - Switch to using sphinx-build - Cleanup doc/source/conf.py to remove now obsolete content. - Use newer openstackdocstheme version, use apidoc for API docs - Fix doc problems found Change-Id: I1f92444a145030e7715a8d357870d712c5d3cfb1
This commit is contained in:
parent
e73f13e3ed
commit
679e39587d
|
@ -2,7 +2,8 @@
|
||||||
# of appearance. Changing the order has an impact on the overall integration
|
# of appearance. Changing the order has an impact on the overall integration
|
||||||
# process, which may cause wedges in the gate later.
|
# process, which may cause wedges in the gate later.
|
||||||
sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.2 # BSD
|
sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.2 # BSD
|
||||||
openstackdocstheme>=1.20.0 # Apache-2.0
|
openstackdocstheme>=1.31.2 # Apache-2.0
|
||||||
|
sphinxcontrib-apidoc>=0.2.0 # Apache-2.0
|
||||||
sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
|
sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
|
||||||
sphinxcontrib-httpdomain>=1.6.1 # BSD
|
sphinxcontrib-httpdomain>=1.6.1 # BSD
|
||||||
reno>=2.7.0 # Apache-2.0
|
reno>=2.7.0 # Apache-2.0
|
||||||
|
|
|
@ -5,4 +5,4 @@ Source Code Index
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
autoindex
|
modules
|
||||||
|
|
|
@ -28,6 +28,7 @@ sys.path.insert(0, os.path.abspath('../'))
|
||||||
# They can be extensions coming with Sphinx (named 'sphinx.ext.*')
|
# They can be extensions coming with Sphinx (named 'sphinx.ext.*')
|
||||||
# or your custom ones.
|
# or your custom ones.
|
||||||
extensions = [
|
extensions = [
|
||||||
|
'sphinxcontrib.apidoc',
|
||||||
'sphinx.ext.autodoc',
|
'sphinx.ext.autodoc',
|
||||||
'sphinxcontrib.pecanwsme.rest',
|
'sphinxcontrib.pecanwsme.rest',
|
||||||
'sphinxcontrib.httpdomain',
|
'sphinxcontrib.httpdomain',
|
||||||
|
@ -304,3 +305,15 @@ epub_copyright = u'2012-2015, OpenStack'
|
||||||
|
|
||||||
# Allow duplicate toc entries.
|
# Allow duplicate toc entries.
|
||||||
#epub_tocdup = True
|
#epub_tocdup = True
|
||||||
|
|
||||||
|
# -- sphinxcontrib.apidoc configuration --------------------------------------
|
||||||
|
|
||||||
|
apidoc_module_dir = '../../panko'
|
||||||
|
apidoc_output_dir = 'api'
|
||||||
|
apidoc_excluded_paths = [
|
||||||
|
'tests',
|
||||||
|
'hacking',
|
||||||
|
# happybase is not Python3 compatible, thus skip over them
|
||||||
|
'storage/hbase/*',
|
||||||
|
'storage/impl_hbase.py'
|
||||||
|
]
|
||||||
|
|
|
@ -35,6 +35,7 @@ Overview
|
||||||
install/index
|
install/index
|
||||||
contributor/index
|
contributor/index
|
||||||
webapi/index
|
webapi/index
|
||||||
|
api/index
|
||||||
|
|
||||||
Sample Configuration Files
|
Sample Configuration Files
|
||||||
==========================
|
==========================
|
||||||
|
|
|
@ -26,28 +26,3 @@ app.wsgi
|
||||||
The file ``panko/api/app.wsgi`` sets up the V2 API WSGI
|
The file ``panko/api/app.wsgi`` sets up the V2 API WSGI
|
||||||
application. The file is installed with the rest of the panko
|
application. The file is installed with the rest of the panko
|
||||||
application code, and should not need to be modified.
|
application code, and should not need to be modified.
|
||||||
|
|
||||||
etc/apache2/panko
|
|
||||||
=================
|
|
||||||
|
|
||||||
The ``etc/apache2/panko`` file contains example settings that
|
|
||||||
work with a copy of panko installed via devstack.
|
|
||||||
|
|
||||||
.. literalinclude:: ../../../etc/apache2/panko
|
|
||||||
|
|
||||||
1. On deb-based systems copy or symlink the file to
|
|
||||||
``/etc/apache2/sites-available``. For rpm-based systems the file will go in
|
|
||||||
``/etc/httpd/conf.d``.
|
|
||||||
|
|
||||||
2. Modify the ``WSGIDaemonProcess`` directive to set the ``user`` and
|
|
||||||
``group`` values to an appropriate user on your server. In many
|
|
||||||
installations ``panko`` will be correct.
|
|
||||||
|
|
||||||
3. Enable the panko site. On deb-based systems::
|
|
||||||
|
|
||||||
$ a2ensite panko
|
|
||||||
$ service apache2 reload
|
|
||||||
|
|
||||||
On rpm-based systems::
|
|
||||||
|
|
||||||
$ service httpd reload
|
|
||||||
|
|
|
@ -17,8 +17,9 @@ available in the backend.
|
||||||
.. rest-controller:: panko.api.controllers.v2.capabilities:CapabilitiesController
|
.. rest-controller:: panko.api.controllers.v2.capabilities:CapabilitiesController
|
||||||
:webprefix: /v2/capabilities
|
:webprefix: /v2/capabilities
|
||||||
|
|
||||||
.. autotype:: panko.api.controllers.v2.capabilities.Capabilities
|
.. autoclass:: panko.api.controllers.v2.capabilities.Capabilities
|
||||||
:members:
|
:members:
|
||||||
|
:noindex:
|
||||||
|
|
||||||
Events and Traits
|
Events and Traits
|
||||||
=================
|
=================
|
||||||
|
@ -32,19 +33,21 @@ Events and Traits
|
||||||
.. rest-controller:: panko.api.controllers.v2.events:EventsController
|
.. rest-controller:: panko.api.controllers.v2.events:EventsController
|
||||||
:webprefix: /v2/events
|
:webprefix: /v2/events
|
||||||
|
|
||||||
.. autotype:: panko.api.controllers.v2.events.Event
|
.. autoclass:: panko.api.controllers.v2.events.Event
|
||||||
:members:
|
:members:
|
||||||
|
:noindex:
|
||||||
|
|
||||||
.. autotype:: panko.api.controllers.v2.events.Trait
|
.. autoclass:: panko.api.controllers.v2.events.Trait
|
||||||
:members:
|
:members:
|
||||||
|
:noindex:
|
||||||
|
|
||||||
.. autotype:: panko.api.controllers.v2.events.TraitDescription
|
.. autoclass:: panko.api.controllers.v2.events.TraitDescription
|
||||||
:members:
|
:members:
|
||||||
|
:noindex:
|
||||||
|
|
||||||
Filtering Queries
|
Filtering Queries
|
||||||
=================
|
=================
|
||||||
|
|
||||||
See :ref:`api-queries` for how to query the API.
|
.. autoclass:: panko.api.controllers.v2.events.EventQuery
|
||||||
|
|
||||||
.. autotype:: panko.api.controllers.v2.events.EventQuery
|
|
||||||
:members:
|
:members:
|
||||||
|
:noindex:
|
||||||
|
|
|
@ -144,10 +144,6 @@ html_theme = 'openstackdocs'
|
||||||
# directly to the root of the documentation.
|
# directly to the root of the documentation.
|
||||||
# html_extra_path = []
|
# html_extra_path = []
|
||||||
|
|
||||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
|
||||||
# using the given strftime format.
|
|
||||||
html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
|
||||||
|
|
||||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||||
# typographically correct entities.
|
# typographically correct entities.
|
||||||
# html_use_smartypants = True
|
# html_use_smartypants = True
|
||||||
|
|
|
@ -54,10 +54,6 @@ oslo.policy.policies =
|
||||||
oslo.config.opts.defaults =
|
oslo.config.opts.defaults =
|
||||||
panko = panko.conf.defaults:set_cors_middleware_defaults
|
panko = panko.conf.defaults:set_cors_middleware_defaults
|
||||||
|
|
||||||
[pbr]
|
|
||||||
warnerrors = true
|
|
||||||
autodoc_index_modules = true
|
|
||||||
|
|
||||||
[extract_messages]
|
[extract_messages]
|
||||||
keywords = _ gettext ngettext l_ lazy_gettext
|
keywords = _ gettext ngettext l_ lazy_gettext
|
||||||
mapping_file = babel.cfg
|
mapping_file = babel.cfg
|
||||||
|
|
7
tox.ini
7
tox.ini
|
@ -2,6 +2,7 @@
|
||||||
minversion = 2.0
|
minversion = 2.0
|
||||||
skipsdist = True
|
skipsdist = True
|
||||||
envlist = py{37}{,-mongodb,-mysql,-postgresql,-elasticsearch},pep8
|
envlist = py{37}{,-mongodb,-mysql,-postgresql,-elasticsearch},pep8
|
||||||
|
ignore_basepython_conflict = True
|
||||||
|
|
||||||
[testenv]
|
[testenv]
|
||||||
basepython = python3
|
basepython = python3
|
||||||
|
@ -49,9 +50,9 @@ commands = oslo-config-generator --config-file=etc/panko/panko-config-generator.
|
||||||
commands = oslopolicy-sample-generator --config-file=etc/panko/panko-policy-generator.conf
|
commands = oslopolicy-sample-generator --config-file=etc/panko/panko-policy-generator.conf
|
||||||
|
|
||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
deps = -r{toxinidir}/doc/requirements.txt
|
deps = -r{toxinidir}/requirements.txt
|
||||||
commands = python setup.py build_sphinx
|
-r{toxinidir}/doc/requirements.txt
|
||||||
setenv = PYTHONHASHSEED=0
|
commands = sphinx-build -W -b html doc/source doc/build/html
|
||||||
|
|
||||||
[testenv:pdf-docs]
|
[testenv:pdf-docs]
|
||||||
deps = {[testenv:docs]deps}
|
deps = {[testenv:docs]deps}
|
||||||
|
|
Loading…
Reference in New Issue