From 3b773fb717d531a3a30271bff374aa0bd85edd82 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 17 Dec 2019 16:35:57 +0000 Subject: [PATCH] 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 | 3 ++- doc/requirements.txt | 1 + doc/source/conf.py | 36 ++++++----------------------- doc/source/reference/index.rst | 42 ++++------------------------------ setup.cfg | 9 -------- tox.ini | 19 ++++++++------- 6 files changed, 26 insertions(+), 84 deletions(-) diff --git a/.gitignore b/.gitignore index d3b8ec1..0c94d4b 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/requirements.txt b/doc/requirements.txt index 2a8d917..1b0cdda 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 095b0b8..02673cc 100755 --- a/doc/source/conf.py +++ b/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} diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 99ead69..de91fbb 100644 --- a/doc/source/reference/index.rst +++ b/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 diff --git a/setup.cfg b/setup.cfg index cb86223..562b2a3 100644 --- a/setup.cfg +++ b/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 diff --git a/tox.ini b/tox.ini index d0dbce6..dddf835 100644 --- a/tox.ini +++ b/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