From 2610dff995e78fdaa0187b8a3aea17c4b46c7b18 Mon Sep 17 00:00:00 2001 From: Ben Nemec Date: Tue, 18 Jun 2019 16:31:48 +0000 Subject: [PATCH] Switch to sphinxcontrib-apidoc Rather than have the API docs hand-curated and scattered throughout the documentation, let's use the apidoc module like all of the other Oslo projects so our API docs are consistent and easy to find. The documents that were exclusively API docs are removed entirely, and the ones where API docs were included with other content have been changed to reference the generated API docs rather than include them inline. The one exception is the drivers because they are in private modules that don't show up in the API docs. Those are still explicitly documented. Change-Id: I00bdd963e0d4f270c0d4b50c05f420317a137fd5 --- doc/requirements.txt | 1 + doc/source/cli/generator.rst | 11 +---------- doc/source/conf.py | 9 +++++++++ doc/source/reference/cfgfilter.rst | 5 ----- doc/source/reference/configopts.rst | 8 -------- doc/source/reference/drivers.rst | 5 ++++- doc/source/reference/exceptions.rst | 20 -------------------- doc/source/reference/fixture.rst | 8 -------- doc/source/reference/helpers.rst | 5 ----- doc/source/reference/index.rst | 8 +------- doc/source/reference/opts.rst | 25 ------------------------- doc/source/reference/parser.rst | 8 -------- doc/source/reference/types.rst | 6 ------ oslo_config/sphinxext.py | 1 + 14 files changed, 17 insertions(+), 103 deletions(-) delete mode 100644 doc/source/reference/cfgfilter.rst delete mode 100644 doc/source/reference/configopts.rst delete mode 100644 doc/source/reference/exceptions.rst delete mode 100644 doc/source/reference/fixture.rst delete mode 100644 doc/source/reference/opts.rst delete mode 100644 doc/source/reference/parser.rst delete mode 100644 doc/source/reference/types.rst diff --git a/doc/requirements.txt b/doc/requirements.txt index e478ee6a..5f4e8e28 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -4,6 +4,7 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD +sphinxcontrib-apidoc>=0.2.0 # BSD openstackdocstheme>=1.18.1 # Apache-2.0 reno>=2.5.0 # Apache-2.0 fixtures>=3.0.0 # Apache-2.0/BSD diff --git a/doc/source/cli/generator.rst b/doc/source/cli/generator.rst index cada1423..99e3bd7a 100644 --- a/doc/source/cli/generator.rst +++ b/doc/source/cli/generator.rst @@ -289,7 +289,7 @@ where the top-level keys are: the ``OptGroup`` they are assigned to which defaults to ``DEFAULT`` if unset. For information on the various attributes of each option, refer to - :ref:`option-definitions`. + :class:`oslo_config.cfg.Opt` and its subclasses. ``deprecated_options`` @@ -358,12 +358,3 @@ facilitate this, options can be supplied with a ``sample_default`` attribute: cfg.StrOpt('base_dir' default=os.getcwd(), sample_default='/usr/lib/myapp') - -API ---- - -.. currentmodule:: oslo_config.generator - -.. autofunction:: main -.. autofunction:: generate -.. autofunction:: register_cli_opts diff --git a/doc/source/conf.py b/doc/source/conf.py index ec59f02f..52ac17b8 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -13,6 +13,7 @@ extensions = [ 'openstackdocstheme', 'oslo_config.sphinxconfiggen', 'oslo_config.sphinxext', + 'sphinxcontrib.apidoc', ] # openstackdocstheme options @@ -75,3 +76,11 @@ latex_documents = [ '%s Documentation' % project, 'OpenStack Foundation', 'manual'), ] + +# -- sphinxcontrib.apidoc configuration -------------------------------------- + +apidoc_module_dir = '../../oslo_config' +apidoc_output_dir = 'reference/api' +apidoc_excluded_paths = [ + 'tests', +] diff --git a/doc/source/reference/cfgfilter.rst b/doc/source/reference/cfgfilter.rst deleted file mode 100644 index c11cddd9..00000000 --- a/doc/source/reference/cfgfilter.rst +++ /dev/null @@ -1,5 +0,0 @@ --------------------- -The cfgfilter Module --------------------- - -.. automodule:: oslo_config.cfgfilter diff --git a/doc/source/reference/configopts.rst b/doc/source/reference/configopts.rst deleted file mode 100644 index 06c9c3b6..00000000 --- a/doc/source/reference/configopts.rst +++ /dev/null @@ -1,8 +0,0 @@ --------------------- -The ConfigOpts Class --------------------- - -.. currentmodule:: oslo_config.cfg - -.. autoclass:: ConfigOpts - :members: diff --git a/doc/source/reference/drivers.rst b/doc/source/reference/drivers.rst index 0c06ab17..91807c66 100644 --- a/doc/source/reference/drivers.rst +++ b/doc/source/reference/drivers.rst @@ -3,11 +3,14 @@ Backend Drivers --------------- -.. automodule:: oslo_config.sources +Refer to :py:mod:`oslo_config.sources` Known Backend Drivers --------------------- +.. NOTE(bnemec): These are private modules, so we need to explicitly + document them + .. automodule:: oslo_config.sources._uri .. automodule:: oslo_config.sources._environment diff --git a/doc/source/reference/exceptions.rst b/doc/source/reference/exceptions.rst deleted file mode 100644 index 8036b842..00000000 --- a/doc/source/reference/exceptions.rst +++ /dev/null @@ -1,20 +0,0 @@ ----------- -Exceptions ----------- - -.. currentmodule:: oslo_config.cfg - -.. autoexception:: Error -.. autoexception:: NotInitializedError -.. autoexception:: ArgsAlreadyParsedError -.. autoexception:: NoSuchOptError -.. autoexception:: NoSuchGroupError -.. autoexception:: DuplicateOptError -.. autoexception:: RequiredOptError -.. autoexception:: TemplateSubstitutionError -.. autoexception:: ConfigFilesNotFoundError -.. autoexception:: ConfigFilesPermissionDeniedError -.. autoexception:: ConfigDirNotFoundError -.. autoexception:: ConfigFileParseError -.. autoexception:: ConfigFileValueError -.. autoexception:: DefaultValueError diff --git a/doc/source/reference/fixture.rst b/doc/source/reference/fixture.rst deleted file mode 100644 index 47c4939f..00000000 --- a/doc/source/reference/fixture.rst +++ /dev/null @@ -1,8 +0,0 @@ ------------- -Test Fixture ------------- - -.. currentmodule:: oslo_config.fixture - -.. autoclass:: Config - :members: diff --git a/doc/source/reference/helpers.rst b/doc/source/reference/helpers.rst index 4a36dc89..e9ee18af 100644 --- a/doc/source/reference/helpers.rst +++ b/doc/source/reference/helpers.rst @@ -2,11 +2,6 @@ Helper Functions ---------------- -.. currentmodule:: oslo_config.cfg - -.. autofunction:: find_config_files -.. autofunction:: set_defaults - Showing detailed locations for configuration settings ----------------------------------------------------- diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 3a6290df..a4593f8c 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -5,6 +5,7 @@ .. toctree:: :maxdepth: 2 + API defining naming accessing @@ -12,14 +13,7 @@ command-line deprecating globals - opts - types - configopts - cfgfilter helpers - fixture - parser - exceptions styleguide mutable locations diff --git a/doc/source/reference/opts.rst b/doc/source/reference/opts.rst deleted file mode 100644 index b7532ed8..00000000 --- a/doc/source/reference/opts.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _option-definitions: - -==================== - Opt and Subclasses -==================== - -.. currentmodule:: oslo_config.cfg - -.. autoclass:: Opt -.. autoclass:: StrOpt -.. autoclass:: BoolOpt -.. autoclass:: IntOpt -.. autoclass:: FloatOpt -.. autoclass:: ListOpt -.. autoclass:: DictOpt -.. autoclass:: MultiOpt -.. autoclass:: MultiStrOpt -.. autoclass:: IPOpt -.. autoclass:: PortOpt -.. autoclass:: HostnameOpt -.. autoclass:: HostAddressOpt -.. autoclass:: URIOpt -.. autoclass:: DeprecatedOpt -.. autoclass:: SubCommandOpt -.. autoclass:: OptGroup diff --git a/doc/source/reference/parser.rst b/doc/source/reference/parser.rst deleted file mode 100644 index 2d9430f0..00000000 --- a/doc/source/reference/parser.rst +++ /dev/null @@ -1,8 +0,0 @@ ------------- -File Parsing ------------- - -.. autoclass:: oslo_config.iniparser.BaseParser - -.. autoclass:: oslo_config.cfg.ConfigParser - :members: parse diff --git a/doc/source/reference/types.rst b/doc/source/reference/types.rst deleted file mode 100644 index 848d75de..00000000 --- a/doc/source/reference/types.rst +++ /dev/null @@ -1,6 +0,0 @@ -============================= - Option Types and Validation -============================= - -.. automodule:: oslo_config.types - :members: diff --git a/oslo_config/sphinxext.py b/oslo_config/sphinxext.py index 9a0da869..0f32c203 100644 --- a/oslo_config/sphinxext.py +++ b/oslo_config/sphinxext.py @@ -474,6 +474,7 @@ class ConfigDomain(Domain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + """Resolve cross-references""" if typ == 'option': group_name, option_name = target.split('.', 1) return make_refnode(