From 3c059cb701e55c7c550f2bbe9626c9c063b0d77e Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Tue, 13 Jun 2017 16:59:39 -0400 Subject: [PATCH] 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 --- doc/source/index.rst | 11 +++++++ pbr/builddoc.py | 7 ++-- pbr/tests/test_setup.py | 72 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 2 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 764edf1f..4ff2d7a8 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/pbr/builddoc.py b/pbr/builddoc.py index 1d31502f..c1a2e6f4 100644 --- a/pbr/builddoc.py +++ b/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 diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py index 02136033..0b9c81be 100644 --- a/pbr/tests/test_setup.py +++ b/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 = [