Merge "Switch to sphinxcontrib-apidoc"

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(