allow user to override the output location of api docs

Allow the user to specify 'api_doc_dir' in the build_sphinx section of
their setup.cfg to control where the auto-generated API documentation is
written.

Change-Id: I2bd5652bb59cbd9c939931ba2e7db1b37d2b30bb
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/index.rst

@@ -321,6 +321,12 @@ The ``pbr`` section controls `pbr` specific options and behaviours.
   A list of modules to exclude when building module documentation using `pbr`.
   `fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
 
+``api_doc_dir``
+
+  A subdirectory inside the ``build_sphinx.source_dir`` where
+  auto-generated API documentation should be written, if
+  ``autodoc_index_modules`` is set to True. Defaults to ``"api"``.
+
 .. note::
 
    When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may
@@ -374,6 +380,11 @@ option.
       build-dir = doc/build
       all-files = 1
 
+``source_dir``
+
+  The path to the source directory where the Sphinx documentation tree
+  is.
+
 For information on the remaining options, refer to the `Sphinx
 documentation`__. In addition, the ``autodoc_index_modules``,
 ``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and

pbr/builddoc.py

@@ -69,10 +69,13 @@ class LocalBuildDoc(setup_command.BuildDoc):
 
     def _get_source_dir(self):
         option_dict = self.distribution.get_option_dict('build_sphinx')
+        pbr_option_dict = self.distribution.get_option_dict('pbr')
+        _, api_doc_dir = pbr_option_dict.get('api_doc_dir', (None, 'api'))
         if 'source_dir' in option_dict:
-            source_dir = os.path.join(option_dict['source_dir'][1], 'api')
+            source_dir = os.path.join(option_dict['source_dir'][1],
+                                      api_doc_dir)
         else:
-            source_dir = 'doc/source/api'
+            source_dir = 'doc/source/' + api_doc_dir
         if not os.path.exists(source_dir):
             os.makedirs(source_dir)
         return source_dir

pbr/tests/test_setup.py

@@ -376,6 +376,78 @@ class BuildSphinxTest(BaseSphinxTest):
         self.assertEqual(["builder1", "builder2"], build_doc.builders)
 
 
+class APIAutoDocTest(base.BaseTestCase):
+
+    def setUp(self):
+        super(APIAutoDocTest, self).setUp()
+
+        # setup_command requires the Sphinx instance to have some
+        # attributes that aren't set normally with the way we use the
+        # class (because we replace the constructor). Add default
+        # values directly to the class definition.
+        import sphinx.application
+        sphinx.application.Sphinx.messagelog = []
+        sphinx.application.Sphinx.statuscode = 0
+
+        self.useFixture(fixtures.MonkeyPatch(
+            "sphinx.application.Sphinx.__init__", lambda *a, **kw: None))
+        self.useFixture(fixtures.MonkeyPatch(
+            "sphinx.application.Sphinx.build", lambda *a, **kw: None))
+        self.useFixture(fixtures.MonkeyPatch(
+            "sphinx.application.Sphinx.config", _SphinxConfig))
+        self.useFixture(fixtures.MonkeyPatch(
+            "sphinx.config.Config.init_values", lambda *a: None))
+        self.useFixture(fixtures.MonkeyPatch(
+            "sphinx.config.Config.__init__", lambda *a: None))
+        from distutils import dist
+        self.distr = dist.Distribution()
+        self.distr.packages = ("fake_package",)
+        self.distr.command_options["build_sphinx"] = {
+            "source_dir": ["a", "."]}
+        self.sphinx_options = self.distr.command_options["build_sphinx"]
+        pkg_fixture = fixtures.PythonPackage(
+            "fake_package", [("fake_module.py", b""),
+                             ("another_fake_module_for_testing.py", b""),
+                             ("fake_private_module.py", b"")])
+        self.useFixture(pkg_fixture)
+        self.useFixture(base.DiveDir(pkg_fixture.base))
+        self.pbr_options = self.distr.command_options.setdefault('pbr', {})
+        self.pbr_options["autodoc_index_modules"] = ('setup.cfg', 'True')
+
+    def test_default_api_build_dir(self):
+        build_doc = packaging.LocalBuildDoc(self.distr)
+        build_doc.run()
+
+        print('PBR OPTIONS:', self.pbr_options)
+        print('DISTR OPTIONS:', self.distr.command_options)
+
+        self.assertTrue(os.path.exists("api/autoindex.rst"))
+        self.assertTrue(os.path.exists("api/fake_package.fake_module.rst"))
+        self.assertTrue(
+            os.path.exists(
+                "api/fake_package.fake_private_module.rst"))
+        self.assertTrue(
+            os.path.exists(
+                "api/fake_package.another_fake_module_for_testing.rst"))
+
+    def test_different_api_build_dir(self):
+        # Options have to come out of the settings dict as a tuple
+        # showing the source and the value.
+        self.pbr_options['api_doc_dir'] = (None, 'contributor/api')
+        build_doc = packaging.LocalBuildDoc(self.distr)
+        build_doc.run()
+
+        print('PBR OPTIONS:', self.pbr_options)
+        print('DISTR OPTIONS:', self.distr.command_options)
+
+        self.assertTrue(os.path.exists("contributor/api/autoindex.rst"))
+        self.assertTrue(
+            os.path.exists("contributor/api/fake_package.fake_module.rst"))
+        self.assertTrue(
+            os.path.exists(
+                "contributor/api/fake_package.fake_private_module.rst"))
+
+
 class ParseRequirementsTestScenarios(base.BaseTestCase):
 
     versioned_scenarios = [