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

doc/requirements.txt

@@ -2,7 +2,8 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 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-httpdomain>=1.6.1 # BSD
 reno>=2.7.0 # Apache-2.0

doc/source/api/index.rst

@@ -5,4 +5,4 @@ Source Code Index
 .. toctree::
    :maxdepth: 1
 
-   autoindex
+   modules

doc/source/conf.py

@@ -28,6 +28,7 @@ sys.path.insert(0, os.path.abspath('../'))
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*')
 # or your custom ones.
 extensions = [
+    'sphinxcontrib.apidoc',
     'sphinx.ext.autodoc',
     'sphinxcontrib.pecanwsme.rest',
     'sphinxcontrib.httpdomain',
@@ -304,3 +305,15 @@ epub_copyright = u'2012-2015, OpenStack'
 
 # Allow duplicate toc entries.
 #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'
+]

doc/source/index.rst

@@ -35,6 +35,7 @@ Overview
    install/index
    contributor/index
    webapi/index
+   api/index
 
 Sample Configuration Files
 ==========================

doc/source/install/mod_wsgi.rst

@@ -26,28 +26,3 @@ app.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 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

doc/source/webapi/v2.rst

@@ -17,8 +17,9 @@ available in the backend.
 .. rest-controller:: panko.api.controllers.v2.capabilities:CapabilitiesController
    :webprefix: /v2/capabilities
 
-.. autotype:: panko.api.controllers.v2.capabilities.Capabilities
+.. autoclass:: panko.api.controllers.v2.capabilities.Capabilities
    :members:
+   :noindex:
 
 Events and Traits
 =================
@@ -32,19 +33,21 @@ Events and Traits
 .. rest-controller:: panko.api.controllers.v2.events:EventsController
    :webprefix: /v2/events
 
-.. autotype:: panko.api.controllers.v2.events.Event
+.. autoclass:: panko.api.controllers.v2.events.Event
    :members:
+   :noindex:
 
-.. autotype:: panko.api.controllers.v2.events.Trait
+.. autoclass:: panko.api.controllers.v2.events.Trait
    :members:
+   :noindex:
 
-.. autotype:: panko.api.controllers.v2.events.TraitDescription
+.. autoclass:: panko.api.controllers.v2.events.TraitDescription
    :members:
+   :noindex:
 
 Filtering Queries
 =================
 
-See :ref:`api-queries` for how to query the API.
-
-.. autotype:: panko.api.controllers.v2.events.EventQuery
+.. autoclass:: panko.api.controllers.v2.events.EventQuery
    :members:
+   :noindex:

releasenotes/source/conf.py

@@ -144,10 +144,6 @@ html_theme = 'openstackdocs'
 # directly to the root of the documentation.
 # 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
 # typographically correct entities.
 # html_use_smartypants = True

setup.cfg

@@ -54,10 +54,6 @@ oslo.policy.policies =
 oslo.config.opts.defaults =
     panko = panko.conf.defaults:set_cors_middleware_defaults
 
-[pbr]
-warnerrors = true
-autodoc_index_modules = true
-
 [extract_messages]
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg

tox.ini

@@ -2,6 +2,7 @@
 minversion = 2.0
 skipsdist = True
 envlist = py{37}{,-mongodb,-mysql,-postgresql,-elasticsearch},pep8
+ignore_basepython_conflict = True
 
 [testenv]
 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
 
 [testenv:docs]
-deps = -r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
-setenv = PYTHONHASHSEED=0
+deps = -r{toxinidir}/requirements.txt
+       -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:pdf-docs]
 deps = {[testenv:docs]deps}