Allow sphinx to use multiple cpus w -j support (#18900)

'CPUS=6 make webdocs' for example

docsite/Makefile

@@ -1,11 +1,12 @@
 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 FORMATTER=../hacking/module_formatter.py
 DUMPER=../hacking/dump_playbook_attributes.py
+CPUS ?= 1
 
 all: clean docs
 
 docs: clean directives modules staticmin
-	./build-site.py
+	./build-site.py -j $(CPUS)
 	-(cp *.ico htmlout/)
 	-(cp *.jpg htmlout/)
 	-(cp *.png htmlout/)
@@ -15,10 +16,10 @@ variables:
 	dot variables.dot -Tpng -o htmlout/variables.png
 
 viewdocs: clean staticmin
-	./build-site.py view
+	./build-site.py -j $(CPUS) view
 
 htmldocs: staticmin
-	./build-site.py rst
+	./build-site.py -j $(CPUS) rst
 
 webdocs: htmldocs
 

docsite/build-site.py

@@ -19,6 +19,7 @@ from __future__ import print_function
 
 __docformat__ = 'restructuredtext'
 
+import optparse
 import os
 import sys
 import traceback
@@ -29,7 +30,6 @@ except ImportError:
     print("Dependency missing: Python Sphinx")
     print("#################################")
     sys.exit(1)
-import os
 
 
 class SphinxBuilder(object):
@@ -37,7 +37,7 @@ class SphinxBuilder(object):
     Creates HTML documentation using Sphinx.
     """
 
-    def __init__(self):
+    def __init__(self, verbosity=None, parallel=None):
         """
         Run the DocCommand.
         """
@@ -58,15 +58,18 @@ class SphinxBuilder(object):
             freshenv = True
 
             # Create the builder
+            # __init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides=None, status=<open file '<stdout>', mode 'w'>, warning=<open file '<stderr>', mode 'w'>, freshenv=False, warningiserror=False, tags=None, verbosity=0, parallel=0)
             app = Sphinx(srcdir,
-                              confdir,
-                              outdir,
-                              doctreedir,
-                              buildername,
-                              {},
-                              sys.stdout,
-                              sys.stderr,
-                              freshenv)
+                         confdir,
+                         outdir,
+                         doctreedir,
+                         buildername,
+                         confoverrides={},
+                         status=sys.stdout,
+                         warning=sys.stderr,
+                         freshenv=freshenv,
+                         verbosity=verbosity,
+                         parallel=parallel)
 
             app.builder.build_all()
 
@@ -78,20 +81,31 @@ class SphinxBuilder(object):
     def build_docs(self):
         self.app.builder.build_all()
 
+def build_rst_docs(verbosity=None, parallel=None):
+    verbosity = verbosity or 1
+    parallel = parallel or 1
+    SphinxBuilder(verbosity=verbosity,
+                  parallel=parallel)
 
-def build_rst_docs():
-    docgen = SphinxBuilder()
+USAGE = """This script builds the html documentation from rst/asciidoc sources.\n")
+Run 'make docs' to build everything.\n
+Run 'make viewdocs' to build and then preview in a web browser."""
 
 if __name__ == '__main__':
-    if '-h' in sys.argv or '--help' in sys.argv:
-        print("This script builds the html documentation from rst/asciidoc sources.\n")
-        print("    Run 'make docs' to build everything.")
-        print("    Run 'make viewdocs' to build and then preview in a web browser.")
-        sys.exit(0)
 
-    build_rst_docs()
+    parser = optparse.OptionParser(USAGE)
+    parser.add_option('-v','--verbose', dest='verbosity', default=0, action="count",
+                      help="verbose mode (-vvv for more, -vvvv to enable connection debugging)")
+    parser.add_option('-j', '--parallel', dest='parallel', default="1", action='store',
+                      help="Number of threads to start")
+    parser.add_option('--view', dest='view',
+                      help="Open a browser after building docs")
+
+    options, args = parser.parse_args(sys.argv[:])
+
+    build_rst_docs(verbosity=options.verbosity, parallel=int(options.parallel))
 
-    if "view" in sys.argv:
+    if hasattr(options, 'view'):
         import webbrowser
         if not webbrowser.open('htmlout/index.html'):
             print("Could not open on your webbrowser.", file=sys.stderr)