summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorStephen Finucane <sfinucan@redhat.com>2017-04-12 10:38:31 +0100
committerStephen Finucane <sfinucan@redhat.com>2017-04-14 18:05:22 +0000
commitd4e4efd77963ef95906cfbac73468f80cd8e3330 (patch)
tree94cd88dbef39a6a803fc9206118cd10630b7e591
parent54fb6e71b71b8467352edd745399940444aac435 (diff)
Stop building man pages by default
From pretty much the beginning [1], pbr has defaulted to building both man page and html output, but has failed to document it anywhere. People tend to copy-paste their 'setup.py' and 'conf.py', or rely on the 'cookiecutter' project, with very little understanding of what's going on under the hood (and why would you care - it's docs :)). This means that the vast majority of folks using 'pbr' (basically everyone in OpenStack) have been unwittingly building "man pages" as part of their doc builds for no good reason, which has also led to a lot of confusion when this magic behavior is the cause of bugs [2][3]. There's no good reason that pbr should default to building both man pages and html output. For folks that want this functionality, we should document it so they can use it. For everyone else though, let's do the sane thing and output html like the standard 'build_sphinx' plugin. [1] https://github.com/openstack-dev/pbr/commit/5b8b7f1d [2] https://bugs.launchpad.net/pbr/+bug/1681983 [3] https://bugs.launchpad.net/oslotest/+bug/1379998 Change-Id: I579134a2b7980669180c1666503b848835cc2957 Closes-Bug: #1681983
Notes
Notes (review): Code-Review+2: Monty Taylor <mordred@inaugust.com> Code-Review+2: Julien Danjou <julien@danjou.info> Workflow+1: ChangBo Guo(gcb) <glongwave@gmail.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Sat, 15 Apr 2017 15:00:46 +0000 Reviewed-on: https://review.openstack.org/456156 Project: openstack-dev/pbr Branch: refs/heads/master
-rw-r--r--doc/source/index.rst6
-rw-r--r--pbr/builddoc.py6
-rw-r--r--pbr/tests/test_setup.py3
3 files changed, 8 insertions, 7 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4a4e90a..764edf1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -380,6 +380,12 @@ documentation`__. In addition, the ``autodoc_index_modules``,
380``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output 380``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output
381of the automatic module documentation generation. 381of the automatic module documentation generation.
382 382
383.. versionchanged:: 3.0
384
385 The ``build_sphinx`` plugin used to default to building both HTML and man
386 page output. This is no longer the case, and you should explicitly set
387 ``builders`` to ``html man`` if you wish to retain this behavior.
388
383__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html 389__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
384__ http://www.sphinx-doc.org/en/stable/setuptools.html 390__ http://www.sphinx-doc.org/en/stable/setuptools.html
385 391
diff --git a/pbr/builddoc.py b/pbr/builddoc.py
index eedbd16..cd522c6 100644
--- a/pbr/builddoc.py
+++ b/pbr/builddoc.py
@@ -63,7 +63,7 @@ def _find_modules(arg, dirname, files):
63 63
64class LocalBuildDoc(setup_command.BuildDoc): 64class LocalBuildDoc(setup_command.BuildDoc):
65 65
66 builders = ['html', 'man'] 66 builders = ['html']
67 command_name = 'build_sphinx' 67 command_name = 'build_sphinx'
68 sphinx_initialized = False 68 sphinx_initialized = False
69 69
@@ -142,10 +142,6 @@ class LocalBuildDoc(setup_command.BuildDoc):
142 self.builder_target_dir, self.doctree_dir, 142 self.builder_target_dir, self.doctree_dir,
143 self.builder, confoverrides, status_stream, 143 self.builder, confoverrides, status_stream,
144 freshenv=self.fresh_env, warningiserror=self.warning_is_error) 144 freshenv=self.fresh_env, warningiserror=self.warning_is_error)
145 sphinx_config = app.config
146 if self.builder == 'man' and len(
147 getattr(sphinx_config, 'man_pages', '')) == 0:
148 return
149 self.sphinx_initialized = True 145 self.sphinx_initialized = True
150 146
151 try: 147 try:
diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py
index 3d2f401..7aa74f6 100644
--- a/pbr/tests/test_setup.py
+++ b/pbr/tests/test_setup.py
@@ -308,9 +308,8 @@ class BuildSphinxTest(BaseSphinxTest):
308 build_doc = packaging.LocalBuildDoc(self.distr) 308 build_doc = packaging.LocalBuildDoc(self.distr)
309 build_doc.finalize_options() 309 build_doc.finalize_options()
310 310
311 self.assertEqual(2, len(build_doc.builders)) 311 self.assertEqual(1, len(build_doc.builders))
312 self.assertIn('html', build_doc.builders) 312 self.assertIn('html', build_doc.builders)
313 self.assertIn('man', build_doc.builders)
314 313
315 build_doc = packaging.LocalBuildDoc(self.distr) 314 build_doc = packaging.LocalBuildDoc(self.distr)
316 build_doc.builders = '' 315 build_doc.builders = ''