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

14 files changed, 17 insertions, 103 deletions

diff --git a/doc/requirements.txt b/doc/requirements.txt
index e478ee6..5f4e8e2 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 cada142..99e3bd7 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 ec59f02..52ac17b 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 c11cddd..0000000
--- 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 06c9c3b..0000000
--- 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 0c06ab1..91807c6 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 8036b84..0000000
--- 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 47c4939..0000000
--- 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 4a36dc8..e9ee18a 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 3a6290d..a4593f8 100644
--- a/doc/source/reference/index.rst
+++ b/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
diff --git a/doc/source/reference/opts.rst b/doc/source/reference/opts.rst
deleted file mode 100644
index b7532ed..0000000
--- 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 2d9430f..0000000
--- 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 848d75d..0000000
--- 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 9a0da86..0f32c20 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(