DOC: parallelize the number of Sphinx jobs by default (#39364)

Author: afeld

doc/make.py

@@ -39,7 +39,7 @@ class DocBuilder:
 
     def __init__(
         self,
-        num_jobs=0,
+        num_jobs="auto",
         include_api=True,
         whatsnew=False,
         single_doc=None,
@@ -135,7 +135,7 @@ def _sphinx_build(self, kind: str):
 
         cmd = ["sphinx-build", "-b", kind]
         if self.num_jobs:
-            cmd += ["-j", str(self.num_jobs)]
+            cmd += ["-j", self.num_jobs]
         if self.warnings_are_errors:
             cmd += ["-W", "--keep-going"]
         if self.verbosity:
@@ -304,7 +304,7 @@ def main():
         "command", nargs="?", default="html", help=f"command to run: {joined}"
     )
     argparser.add_argument(
-        "--num-jobs", type=int, default=0, help="number of jobs used by sphinx-build"
+        "--num-jobs", default="auto", help="number of jobs used by sphinx-build"
     )
     argparser.add_argument(
         "--no-api", default=False, help="omit api and autosummary", action="store_true"

doc/source/development/contributing.rst

@@ -612,7 +612,8 @@ For comparison, a full documentation build may take 15 minutes, but a single
 section may take 15 seconds. Subsequent builds, which only process portions
 you have changed, will be faster.
 
-You can also specify to use multiple cores to speed up the documentation build::
+The build will automatically use the number of cores available on your machine
+to speed up the documentation build. You can override this::
 
     python make.py html --num-jobs 4