summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDoug Hellmann <doug@doughellmann.com>2017-06-13 16:59:39 -0400
committerDoug Hellmann <doug@doughellmann.com>2017-06-15 12:41:49 -0400
commit3c059cb701e55c7c550f2bbe9626c9c063b0d77e (patch)
tree5a9a7c69116a44ff29a50df7cb9a63d4888a16d0
parentd3b2b79f23ac9125a296fd7972e9a8c0c29e320e (diff)
allow user to override the output location of api docs3.1.0
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>
Notes
Notes (review): Code-Review+2: Julien Danjou <julien@danjou.info> Code-Review+1: Nicolas Bock <nicolasbock@gmail.com> Code-Review+2: Monty Taylor <mordred@inaugust.com> Workflow+1: Monty Taylor <mordred@inaugust.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Fri, 16 Jun 2017 21:58:13 +0000 Reviewed-on: https://review.openstack.org/473983 Project: openstack-dev/pbr Branch: refs/heads/master
-rw-r--r--doc/source/index.rst11
-rw-r--r--pbr/builddoc.py7
-rw-r--r--pbr/tests/test_setup.py72
3 files changed, 88 insertions, 2 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 764edf1..4ff2d7a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -321,6 +321,12 @@ The ``pbr`` section controls `pbr` specific options and behaviours.
321 A list of modules to exclude when building module documentation using `pbr`. 321 A list of modules to exclude when building module documentation using `pbr`.
322 `fnmatch` style pattern (e.g. `myapp.tests.*`) can be used. 322 `fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
323 323
324``api_doc_dir``
325
326 A subdirectory inside the ``build_sphinx.source_dir`` where
327 auto-generated API documentation should be written, if
328 ``autodoc_index_modules`` is set to True. Defaults to ``"api"``.
329
324.. note:: 330.. note::
325 331
326 When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may 332 When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may
@@ -374,6 +380,11 @@ option.
374 build-dir = doc/build 380 build-dir = doc/build
375 all-files = 1 381 all-files = 1
376 382
383``source_dir``
384
385 The path to the source directory where the Sphinx documentation tree
386 is.
387
377For information on the remaining options, refer to the `Sphinx 388For information on the remaining options, refer to the `Sphinx
378documentation`__. In addition, the ``autodoc_index_modules``, 389documentation`__. In addition, the ``autodoc_index_modules``,
379``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and 390``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and
diff --git a/pbr/builddoc.py b/pbr/builddoc.py
index 1d31502..c1a2e6f 100644
--- a/pbr/builddoc.py
+++ b/pbr/builddoc.py
@@ -69,10 +69,13 @@ class LocalBuildDoc(setup_command.BuildDoc):
69 69
70 def _get_source_dir(self): 70 def _get_source_dir(self):
71 option_dict = self.distribution.get_option_dict('build_sphinx') 71 option_dict = self.distribution.get_option_dict('build_sphinx')
72 pbr_option_dict = self.distribution.get_option_dict('pbr')
73 _, api_doc_dir = pbr_option_dict.get('api_doc_dir', (None, 'api'))
72 if 'source_dir' in option_dict: 74 if 'source_dir' in option_dict:
73 source_dir = os.path.join(option_dict['source_dir'][1], 'api') 75 source_dir = os.path.join(option_dict['source_dir'][1],
76 api_doc_dir)
74 else: 77 else:
75 source_dir = 'doc/source/api' 78 source_dir = 'doc/source/' + api_doc_dir
76 if not os.path.exists(source_dir): 79 if not os.path.exists(source_dir):
77 os.makedirs(source_dir) 80 os.makedirs(source_dir)
78 return source_dir 81 return source_dir
diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py
index 0213603..0b9c81b 100644
--- a/pbr/tests/test_setup.py
+++ b/pbr/tests/test_setup.py
@@ -376,6 +376,78 @@ class BuildSphinxTest(BaseSphinxTest):
376 self.assertEqual(["builder1", "builder2"], build_doc.builders) 376 self.assertEqual(["builder1", "builder2"], build_doc.builders)
377 377
378 378
379class APIAutoDocTest(base.BaseTestCase):
380
381 def setUp(self):
382 super(APIAutoDocTest, self).setUp()
383
384 # setup_command requires the Sphinx instance to have some
385 # attributes that aren't set normally with the way we use the
386 # class (because we replace the constructor). Add default
387 # values directly to the class definition.
388 import sphinx.application
389 sphinx.application.Sphinx.messagelog = []
390 sphinx.application.Sphinx.statuscode = 0
391
392 self.useFixture(fixtures.MonkeyPatch(
393 "sphinx.application.Sphinx.__init__", lambda *a, **kw: None))
394 self.useFixture(fixtures.MonkeyPatch(
395 "sphinx.application.Sphinx.build", lambda *a, **kw: None))
396 self.useFixture(fixtures.MonkeyPatch(
397 "sphinx.application.Sphinx.config", _SphinxConfig))
398 self.useFixture(fixtures.MonkeyPatch(
399 "sphinx.config.Config.init_values", lambda *a: None))
400 self.useFixture(fixtures.MonkeyPatch(
401 "sphinx.config.Config.__init__", lambda *a: None))
402 from distutils import dist
403 self.distr = dist.Distribution()
404 self.distr.packages = ("fake_package",)
405 self.distr.command_options["build_sphinx"] = {
406 "source_dir": ["a", "."]}
407 self.sphinx_options = self.distr.command_options["build_sphinx"]
408 pkg_fixture = fixtures.PythonPackage(
409 "fake_package", [("fake_module.py", b""),
410 ("another_fake_module_for_testing.py", b""),
411 ("fake_private_module.py", b"")])
412 self.useFixture(pkg_fixture)
413 self.useFixture(base.DiveDir(pkg_fixture.base))
414 self.pbr_options = self.distr.command_options.setdefault('pbr', {})
415 self.pbr_options["autodoc_index_modules"] = ('setup.cfg', 'True')
416
417 def test_default_api_build_dir(self):
418 build_doc = packaging.LocalBuildDoc(self.distr)
419 build_doc.run()
420
421 print('PBR OPTIONS:', self.pbr_options)
422 print('DISTR OPTIONS:', self.distr.command_options)
423
424 self.assertTrue(os.path.exists("api/autoindex.rst"))
425 self.assertTrue(os.path.exists("api/fake_package.fake_module.rst"))
426 self.assertTrue(
427 os.path.exists(
428 "api/fake_package.fake_private_module.rst"))
429 self.assertTrue(
430 os.path.exists(
431 "api/fake_package.another_fake_module_for_testing.rst"))
432
433 def test_different_api_build_dir(self):
434 # Options have to come out of the settings dict as a tuple
435 # showing the source and the value.
436 self.pbr_options['api_doc_dir'] = (None, 'contributor/api')
437 build_doc = packaging.LocalBuildDoc(self.distr)
438 build_doc.run()
439
440 print('PBR OPTIONS:', self.pbr_options)
441 print('DISTR OPTIONS:', self.distr.command_options)
442
443 self.assertTrue(os.path.exists("contributor/api/autoindex.rst"))
444 self.assertTrue(
445 os.path.exists("contributor/api/fake_package.fake_module.rst"))
446 self.assertTrue(
447 os.path.exists(
448 "contributor/api/fake_package.fake_private_module.rst"))
449
450
379class ParseRequirementsTestScenarios(base.BaseTestCase): 451class ParseRequirementsTestScenarios(base.BaseTestCase):
380 452
381 versioned_scenarios = [ 453 versioned_scenarios = [