Integrate sphinxcontrib-apidoc

This was missed in change Ice407c712b5438b06c4f439c73946640a0c5a86d.
While we're here, we clean up some other bits of mess that were left
behind by that.

Change-Id: Id061758834eaf266766ab7344c4547fce4261e89

.gitignore

@@ -10,6 +10,7 @@
 # git config --global core.excludesfile '~/.gitignore'
 
 *.pyc
+.eggs/
 *.log
 .coverage
 .venv
@@ -20,7 +21,7 @@ oslo.i18n.egg-info/
 skeleton.egg-info/
 build/
 dist/
-doc/source/api
+doc/source/reference/api
 AUTHORS
 .update-venv/
 ChangeLog

doc/requirements.txt

@@ -6,3 +6,4 @@ sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
 sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
 openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0  # BSD

doc/source/conf.py

@@ -12,17 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
+    'sphinxcontrib.apidoc',
     'openstackdocstheme'
 ]
 
@@ -32,13 +28,6 @@ bug_project = 'oslo.i18n'
 bug_tag = ''
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -56,29 +45,18 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = '_theme'
-# html_static_path = ['static']
 html_theme = 'openstackdocs'
 
-html_use_modindex = True
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
+# -- sphinxcontrib.apidoc configuration --------------------------------------
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
+apidoc_module_dir = '../../oslo_i18n'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'tests',
 ]
-
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/reference/index.rst

@@ -1,41 +1,9 @@
 .. _api:
 
-===============
- oslo.i18n API
-===============
+=========================
+ oslo.i18n API Reference
+=========================
 
-oslo_i18n
-=========
+.. toctree::
 
-.. automodule:: oslo_i18n
-
-.. autoclass:: oslo_i18n.TranslatorFactory
-   :members:
-
-.. seealso::
-
-   An example of using a :class:`TranslatorFactory` is provided in
-   :ref:`integration-module`.
-
-.. autofunction:: oslo_i18n.enable_lazy
-
-.. seealso::
-
-   :ref:`lazy-translation`
-
-.. autofunction:: oslo_i18n.translate
-
-.. autofunction:: oslo_i18n.get_available_languages
-
-oslo_i18n.log
-=============
-
-.. automodule:: oslo_i18n.log
-   :members:
-
-oslo_i18n.fixture
-=================
-
-.. automodule:: oslo_i18n.fixture
-   :members:
-   :special-members:
+   api/modules

setup.cfg

@@ -23,15 +23,6 @@ classifier =
 packages =
     oslo_i18n
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-warning-is-error = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = oslo_i18n/locale
 domain = oslo_i18n

tox.ini

@@ -6,8 +6,8 @@ envlist = py27,py37,pep8
 install_command = pip install {opts} {packages}
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
- -r{toxinidir}/test-requirements.txt
- -r{toxinidir}/requirements.txt
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/requirements.txt
 commands = stestr run --slowest {posargs}
 
 [testenv:py27]
@@ -40,12 +40,12 @@ commands =
 [testenv:cover]
 basepython = python3
 setenv =
-    PYTHON=coverage run --source oslo_i18n --parallel-mode
+  PYTHON=coverage run --source oslo_i18n --parallel-mode
 commands =
-    stestr run {posargs}
-    coverage combine
-    coverage html -d cover
-    coverage xml -o cover/coverage.xml
+  stestr run {posargs}
+  coverage combine
+  coverage html -d cover
+  coverage xml -o cover/coverage.xml
 
 
 [flake8]
@@ -62,12 +62,15 @@ exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,__init__.py
 
 [hacking]
 import_exceptions =
-    oslo_i18n._i18n._
+  oslo_i18n._i18n._
 
 [testenv:releasenotes]
 basepython = python3
 whitelist_externals =
   rm
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+  -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf releasenotes/build
   sphinx-build -a -E -W -d releasenotes/build/doctrees --keep-going -b html releasenotes/source releasenotes/build/html