👌 IMPROVE: declare parallel read safe (#225)

.github/workflows/tests.yml

@@ -41,7 +41,6 @@ jobs:
     - name: Run pytest
       run: >
         pytest --durations=10 --cov=sphinx_book_theme --cov-report=xml --cov-report=term-missing
-
     - name: Upload to Codecov
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.7 && github.repository == 'executablebooks/sphinx-book-theme'
       uses: codecov/codecov-action@v1

sphinx_book_theme/__init__.py

@@ -386,3 +386,8 @@ def setup(app: Sphinx):
     app.connect("html-page-context", add_to_context)
 
     app.add_directive("margin", Margin)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

tests/sites/parallel-build/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

tests/sites/parallel-build/conf.py

@@ -0,0 +1,5 @@
+"""
+Sample ``conf.py``.
+"""
+
+html_theme = "sphinx_book_theme"

tests/sites/parallel-build/five.rst

@@ -0,0 +1,3 @@
+=======
+ Five
+=======

tests/sites/parallel-build/four.rst

@@ -0,0 +1,3 @@
+=======
+ Four
+=======

tests/sites/parallel-build/index.rst

@@ -0,0 +1,17 @@
+Samples for substitution directives
+===================================
+
+..
+
+  This is a test of parallel document builds. You need at least 5
+  documents. See:
+  https://github.com/adamtheturtle/sphinx-substitution-extensions/pull/173
+
+.. toctree::
+   :hidden:
+
+   one
+   two
+   three
+   four
+   five

tests/sites/parallel-build/one.rst

@@ -0,0 +1,3 @@
+=====
+ One
+=====

tests/sites/parallel-build/three.rst

@@ -0,0 +1,3 @@
+=======
+ Three
+=======

tests/sites/parallel-build/two.rst

@@ -0,0 +1,3 @@
+=====
+ Two
+=====

tests/test_build.py

@@ -1,6 +1,7 @@
 import os
 from pathlib import Path
 from shutil import copytree
+from subprocess import check_call
 
 from bs4 import BeautifulSoup
 import pytest
@@ -53,6 +54,15 @@ def _func(src_folder, **kwargs):
     yield _func
 
 
+def test_parallel_build():
+    # We cannot use the sphinx_build_factory because SpinxTestApp does
+    # not have a way to pass parallel=2 to the Sphinx constructor
+    # https://github.com/sphinx-doc/sphinx/blob/d8c006f1c0e612d0dc595ae463b8e4c3ebee5ca4/sphinx/testing/util.py#L101
+    check_call(
+        "sphinx-build -j 2 -W -b html tests/sites/parallel-build build", shell=True
+    )
+
+
 def test_build_book(sphinx_build_factory, file_regression):
     """Test building the base book template and config."""
     sphinx_build = sphinx_build_factory("base")  # type: SphinxBuild