From cbede3a3a445b8a6e07b4a8639ce7f56e98871af Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 28 Nov 2019 16:00:24 +1100
Subject: [PATCH] docs: Try to enable parallel reads & writes

Reads still single threaded in Sphinx 1.8.5, though.
---
 docs/build_docs.py                | 1 +
 docs/doxygen_idf.py               | 2 ++
 docs/html_redirects.py            | 2 ++
 docs/idf_build_system/__init__.py | 2 ++
 docs/include_build_file.py        | 2 ++
 docs/kconfig_reference.py         | 2 ++
 docs/link-roles.py                | 2 ++
 docs/toctree_filter.py            | 1 +
 8 files changed, 14 insertions(+)

diff --git a/docs/build_docs.py b/docs/build_docs.py
index dbcb7d638a..4e3932e39b 100755
--- a/docs/build_docs.py
+++ b/docs/build_docs.py
@@ -69,6 +69,7 @@ def build_docs(language, target, build_dir):
         environ['BUILDDIR'] = build_dir
 
         args = [sys.executable, "-m", "sphinx",
+                "-j", "auto",  # use all the cores! (where possible)
                 "-b", "html",  # TODO: PDFs
                 "-d", os.path.join(build_dir, "doctrees"),
                 # TODO: support multiple sphinx-warning.log files, somehow
diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py
index 4cb49b6dd3..af7fb633aa 100644
--- a/docs/doxygen_idf.py
+++ b/docs/doxygen_idf.py
@@ -12,6 +12,8 @@ def setup(app):
     # The idf_build_system extension will emit this event once it
     app.connect('idf-info', generate_doxygen)
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
+
 
 def _parse_defines(header_path):
     defines = {}
diff --git a/docs/html_redirects.py b/docs/html_redirects.py
index ec2811c33e..45a28cac37 100644
--- a/docs/html_redirects.py
+++ b/docs/html_redirects.py
@@ -45,6 +45,8 @@ def setup(app):
     # to create HTML redirects
     app.connect('html-collect-pages', create_redirect_pages)
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
+
 
 def create_redirect_pages(app):
     if not isinstance(app.builder, StandaloneHTMLBuilder):
diff --git a/docs/idf_build_system/__init__.py b/docs/idf_build_system/__init__.py
index b9e4b2db18..9f3e662ed0 100644
--- a/docs/idf_build_system/__init__.py
+++ b/docs/idf_build_system/__init__.py
@@ -26,6 +26,8 @@ def setup(app):
     # we want this to run early in the docs build but unclear exactly when
     app.connect('env-get-outdated', generate_idf_info)
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
+
 def generate_idf_info(app, env, added, changed, removed):
     print("Running CMake on dummy project to get build info...")
     build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
diff --git a/docs/include_build_file.py b/docs/include_build_file.py
index 0eb153cc73..84bc296e1d 100644
--- a/docs/include_build_file.py
+++ b/docs/include_build_file.py
@@ -16,3 +16,5 @@ class IncludeBuildFile(BaseInclude, SphinxDirective):
 
 def setup(app):
       directives.register_directive('include-build-file', IncludeBuildFile)
+
+      return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
diff --git a/docs/kconfig_reference.py b/docs/kconfig_reference.py
index 7cf5a41fde..7137093e56 100644
--- a/docs/kconfig_reference.py
+++ b/docs/kconfig_reference.py
@@ -10,6 +10,8 @@ def setup(app):
     # has parsed the IDF project's information
     app.connect('idf-info', generate_reference)
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
+
 def generate_reference(app, project_description):
     build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
 
diff --git a/docs/link-roles.py b/docs/link-roles.py
index e97eb2e6e9..2c748500d5 100644
--- a/docs/link-roles.py
+++ b/docs/link-roles.py
@@ -46,6 +46,8 @@ def setup(app):
 
     app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
+
 
 def autolink(pattern):
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
diff --git a/docs/toctree_filter.py b/docs/toctree_filter.py
index be58a8c0fc..7082fad7b3 100644
--- a/docs/toctree_filter.py
+++ b/docs/toctree_filter.py
@@ -7,6 +7,7 @@ from sphinx.util import docname_join
 def setup(app):
     app.add_directive('toctree', TocTreeFilt, override=True)
 
+    return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' }
 
 class TocTreeFilt(TocTree):
     """