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

'CPUS=6 make webdocs' for example
This commit is contained in:
Adrian Likins 2016-12-13 14:34:21 -05:00 committed by GitHub
parent 0b8011436d
commit 2979488b08
2 changed files with 37 additions and 22 deletions

View file

@ -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

View file

@ -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)
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")
if "view" in sys.argv:
options, args = parser.parse_args(sys.argv[:])
build_rst_docs(verbosity=options.verbosity, parallel=int(options.parallel))
if hasattr(options, 'view'):
import webbrowser
if not webbrowser.open('htmlout/index.html'):
print("Could not open on your webbrowser.", file=sys.stderr)