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

@@ -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

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

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',
+]

doc/source/reference/cfgfilter.rst

@@ -1,5 +0,0 @@
---------------------
-The cfgfilter Module
---------------------
-
-.. automodule:: oslo_config.cfgfilter

doc/source/reference/configopts.rst

@@ -1,8 +0,0 @@
---------------------
-The ConfigOpts Class
---------------------
-
-.. currentmodule:: oslo_config.cfg
-
-.. autoclass:: ConfigOpts
-   :members:

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

doc/source/reference/exceptions.rst

@@ -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

doc/source/reference/fixture.rst

@@ -1,8 +0,0 @@
-------------
-Test Fixture
-------------
-
-.. currentmodule:: oslo_config.fixture
-
-.. autoclass:: Config
-   :members:

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
 -----------------------------------------------------
 

doc/source/reference/index.rst

@@ -5,6 +5,7 @@
 .. toctree::
    :maxdepth: 2
 
+   API <api/modules>
    defining
    naming
    accessing
@@ -12,14 +13,7 @@
    command-line
    deprecating
    globals
-   opts
-   types
-   configopts
-   cfgfilter
    helpers
-   fixture
-   parser
-   exceptions
    styleguide
    mutable
    locations

doc/source/reference/opts.rst

@@ -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

doc/source/reference/parser.rst

@@ -1,8 +0,0 @@
-------------
-File Parsing
-------------
-
-.. autoclass:: oslo_config.iniparser.BaseParser
-
-.. autoclass:: oslo_config.cfg.ConfigParser
-   :members: parse

doc/source/reference/types.rst

@@ -1,6 +0,0 @@
-=============================
- Option Types and Validation
-=============================
-
-.. automodule:: oslo_config.types
-   :members:

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(