Allow configuration of tutorials execution

There was a worry that not being able to configure these would make it
more unpleasant to use `tox` for the jobs locally.

.azure/tutorials-linux.yml

@@ -29,6 +29,8 @@ jobs:
 
       - bash: tox -e tutorials
         displayName: "Execute tutorials"
+        env:
+          QISKIT_CELL_TIMEOUT: 300
 
       - task: ArchiveFiles@2
         inputs:

docs/conf.py

@@ -156,7 +156,7 @@
 # Nbsphinx
 # ----------------------------------------------------------------------------------
 
-nbsphinx_timeout = 300
+nbsphinx_timeout = int(os.getenv("QISKIT_CELL_TIMEOUT", "300"))
 nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
 nbsphinx_widgets_path = ""
 nbsphinx_thumbnails = {"**": "_static/images/logo.png"}

tools/execute_tutorials.py

@@ -19,6 +19,7 @@
 """
 
 import argparse
+import functools
 import multiprocessing
 import os
 import pathlib
@@ -30,13 +31,16 @@
 
 
 def worker(
-    notebook_path: pathlib.Path, in_root: pathlib.Path, out_root: typing.Optional[pathlib.Path]
+    notebook_path: pathlib.Path,
+    in_root: pathlib.Path,
+    out_root: typing.Optional[pathlib.Path],
+    timeout: int = -1,
 ) -> typing.Optional[Exception]:
     """Single parallel worker that spawns a Jupyter executor node, executes the given notebook
     within it, and writes out the output."""
     try:
         print(f"({os.getpid()}) Processing '{str(notebook_path)}'", flush=True)
-        processor = ExecutePreprocessor(timeout=300, kernel_name="python3")
+        processor = ExecutePreprocessor(timeout=timeout, kernel_name="python3")
         with open(notebook_path, "r") as fptr:
             notebook = nbformat.read(fptr, as_version=4)
         # Run the notebook with the working  directory set to the folder it resides in.
@@ -60,10 +64,18 @@ def main() -> int:
         "notebook_dirs", type=pathlib.Path, nargs="*", help="Folders containing Jupyter notebooks."
     )
     parser.add_argument(
+        "-o",
         "--out",
         type=pathlib.Path,
         help="Output directory for files. Defaults to same location as input file, overwriting it.",
     )
+    parser.add_argument(
+        "-j",
+        "--num-processes",
+        type=int,
+        default=os.cpu_count(),
+        help="Number of processes to use.",
+    )
     args = parser.parse_args()
     notebooks = sorted(
         {
@@ -72,10 +84,10 @@ def main() -> int:
             for notebook_path in in_root.glob("**/*.ipynb")
         }
     )
-    cpus = os.cpu_count()
-    print(f"Using {cpus} processes.")
-    with multiprocessing.Pool(cpus) as pool:
-        failures = pool.starmap(worker, notebooks)
+    timeout = int(os.getenv("QISKIT_CELL_TIMEOUT", "300"))
+    print(f"Using {args.num_processes} process{'' if args.num_processes == 1 else 'es'}.")
+    with multiprocessing.Pool(args.num_processes) as pool:
+        failures = pool.starmap(functools.partial(worker, timeout=timeout), notebooks)
     num_failures = 0
     for path, failure in zip(notebooks, failures):
         if failure is not None:

tox.ini

@@ -73,8 +73,7 @@ setenv =
   {[testenv]setenv}
   QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
   RUST_DEBUG=1  # Faster to compile.
-passenv =
-  QISKIT_DOCS_BUILD_TUTORIALS
+passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS
 deps =
   setuptools_rust  # This is work around for the bug of tox 3 (see #8606 for more details.)
   -r{toxinidir}/requirements-dev.txt
@@ -100,5 +99,6 @@ basepython = python3
 deps =
   {[testenv:docs]deps}
   -r{toxinidir}/requirements-tutorials.txt
+passenv = {[testenv]passenv}, QISKIT_CELL_TIMEOUT
 commands =
-  python tools/execute_tutorials.py {toxinidir}/docs/tutorials --out={toxinidir}/executed_tutorials
+  python tools/execute_tutorials.py {toxinidir}/docs/tutorials --out={toxinidir}/executed_tutorials {posargs}