setuptools: Support multiple builders

At present, the 'builder' option for the setuptools integration only
supports a single output format, typically HTML, like so:

  [build_sphinx]
  builder = man

There is value in being able to specify multiple format, like so:

  [build_sphinx]
  builder = html man

Make this possible.

Signed-off-by: Stephen Finucane <stephen@that.guru>

AUTHORS

@@ -68,6 +68,7 @@ Other contributors, listed alphabetically, are:
 * Michael Wilson -- Intersphinx HTTP basic auth support
 * Joel Wurtz -- cellspanning support in LaTeX
 * Hong Xu -- svg support in imgmath extension and various bug fixes
+* Stephen Finucane -- setup command improvements and documentation
 
 Many thanks for all contributions!
 

doc/setuptools.rst

@@ -103,13 +103,16 @@ Options for setuptools integration
 
 .. confval:: builder
 
-   The builder to use. Defaults is ``html``.
+   The builder or list of builders to use. Default is ``html``.
 
    This can also be set by passing the `-b` flag to ``setup.py``:
 
    .. code-block:: bash
 
-      $ python setup.py build_sphinx -b
+      $ python setup.py build_sphinx -b $BUILDER
+
+   .. versionchanged:: 1.6
+      This can now be a comma- or space-separated list of builders
 
 .. confval:: warning-is-error
 

sphinx/setup_command.py

@@ -28,7 +28,7 @@ from sphinx.util.osutil import abspath
 
 if False:
     # For type annotation
-    from typing import Any  # NOQA
+    from typing import Any, Tuple  # NOQA
 
 
 class BuildDoc(Command):
@@ -76,7 +76,8 @@ class BuildDoc(Command):
         ('source-dir=', 's', 'Source directory'),
         ('build-dir=', None, 'Build directory'),
         ('config-dir=', 'c', 'Location of the configuration directory'),
-        ('builder=', 'b', 'The builder to use. Defaults to "html"'),
+        ('builder=', 'b', 'The builder (or builders) to use. Can be a comma- '
+         'or space-separated list. Defaults to "html"'),
         ('warning-is-error', 'W', 'Turn warning into errors'),
         ('project=', None, 'The documented project\'s name'),
         ('version=', None, 'The short X.Y version'),
@@ -144,6 +145,7 @@ class BuildDoc(Command):
             self.config_dir = self.source_dir
         self.config_dir = abspath(self.config_dir)
 
+        self.ensure_string_list('builder')  # type: ignore
         if self.build_dir is None:
             build = self.get_finalized_command('build')  # type: ignore
             self.build_dir = os.path.join(abspath(build.build_base), 'sphinx')
@@ -151,8 +153,11 @@ class BuildDoc(Command):
         self.build_dir = abspath(self.build_dir)
         self.doctree_dir = os.path.join(self.build_dir, 'doctrees')
         self.mkpath(self.doctree_dir)  # type: ignore
-        self.builder_target_dir = os.path.join(self.build_dir, self.builder)
-        self.mkpath(self.builder_target_dir)  # type: ignore
+        self.builder_target_dirs = [
+            (builder, os.path.join(self.build_dir, builder))
+            for builder in self.builder]  # type: List[Tuple[str, unicode]]
+        for _, builder_target_dir in self.builder_target_dirs:
+            self.mkpath(builder_target_dir)  # type: ignore
 
     def run(self):
         # type: () -> None
@@ -174,24 +179,28 @@ class BuildDoc(Command):
         if self.copyright:
             confoverrides['copyright'] = self.copyright
 
-        app = None
-        try:
-            with docutils_namespace():
-                app = Sphinx(self.source_dir, self.config_dir,
-                             self.builder_target_dir, self.doctree_dir,
-                             self.builder, confoverrides, status_stream,
-                             freshenv=self.fresh_env,
-                             warningiserror=self.warning_is_error)
-                app.build(force_all=self.all_files)
-                if app.statuscode:
-                    raise DistutilsExecError(
-                        'caused by %s builder.' % app.builder.name)
-        except Exception as exc:
-            handle_exception(app, self, exc, sys.stderr)
-            if not self.pdb:
-                raise SystemExit(1)
+        for builder, builder_target_dir in self.builder_target_dirs:
+            app = None
+
+            try:
+                with docutils_namespace():
+                    app = Sphinx(self.source_dir, self.config_dir,
+                                 builder_target_dir, self.doctree_dir,
+                                 builder, confoverrides, status_stream,
+                                 freshenv=self.fresh_env,
+                                 warningiserror=self.warning_is_error)
+                    app.build(force_all=self.all_files)
+                    if app.statuscode:
+                        raise DistutilsExecError(
+                            'caused by %s builder.' % app.builder.name)
+            except Exception as exc:
+                handle_exception(app, self, exc, sys.stderr)
+                if not self.pdb:
+                    raise SystemExit(1)
+
+            if not self.link_index:
+                continue
 
-        if self.link_index:
             src = app.config.master_doc + app.builder.out_suffix  # type: ignore
             dst = app.builder.get_outfilename('index')  # type: ignore
             os.symlink(src, dst)

tests/test_setup_command.py

@@ -64,6 +64,24 @@ def test_build_sphinx(setup_command):
     assert proc.returncode == 0
 
 
+@pytest.mark.setup_command('-b', 'html,man')
+def test_build_sphinx_multiple_builders(setup_command):
+    proc = setup_command.proc
+    out, err = proc.communicate()
+    print(out)
+    print(err)
+    assert proc.returncode == 0
+
+
+@pytest.mark.setup_command('-b', 'html,bar')
+def test_build_sphinx_multiple_invalid_builders(setup_command):
+    proc = setup_command.proc
+    out, err = proc.communicate()
+    print(out)
+    print(err)
+    assert proc.returncode == 1
+
+
 @pytest.fixture
 def nonascii_srcdir(request, setup_command):
     mb_name = u'\u65e5\u672c\u8a9e'