DOC: add option for skipping execution of code blocks

This should make documentation builds faster for people who aren't
working on the code samples.

Author: afeld

doc/make.py

@@ -41,6 +41,7 @@ def __init__(
         self,
         num_jobs=0,
         include_api=True,
+        no_ipython=False,
         single_doc=None,
         verbosity=0,
         warnings_are_errors=False,
@@ -57,6 +58,9 @@ def __init__(
         elif not include_api:
             os.environ["SPHINX_PATTERN"] = "-api"
 
+        if no_ipython:
+            os.environ["SPHINX_SKIP_IPYTHON"] = "TRUE"
+
         self.single_doc_html = None
         if single_doc and single_doc.endswith(".rst"):
             self.single_doc_html = os.path.splitext(single_doc)[0] + ".html"
@@ -302,6 +306,12 @@ def main():
     argparser.add_argument(
         "--no-api", default=False, help="omit api and autosummary", action="store_true"
     )
+    argparser.add_argument(
+        "--no-ipython",
+        default=False,
+        help="skip execution of code blocks",
+        action="store_true",
+    )
     argparser.add_argument(
         "--single",
         metavar="FILENAME",
@@ -353,6 +363,7 @@ def main():
     builder = DocBuilder(
         args.num_jobs,
         not args.no_api,
+        args.no_ipython,
         args.single,
         args.verbosity,
         args.warnings_are_errors,

doc/source/conf.py

@@ -19,6 +19,7 @@
 
 import jinja2
 from numpydoc.docscrape import NumpyDocString
+from IPython.sphinxext.ipython_directive import IPythonDirective
 from sphinx.ext.autosummary import _import_by_name
 
 logger = logging.getLogger(__name__)
@@ -744,6 +745,16 @@ def rstjinja(app, docname, source):
     source[0] = rendered
 
 
+class SkipIPython(IPythonDirective):
+    """
+    Treats all ipython directives as :verbatim:, to speed up build time.
+    """
+
+    def run(self):
+        self.options["verbatim"] = True
+        return super().run()
+
+
 def setup(app):
     app.connect("source-read", rstjinja)
     app.connect("autodoc-process-docstring", remove_flags_docstring)
@@ -754,3 +765,7 @@ def setup(app):
     app.add_autodocumenter(AccessorMethodDocumenter)
     app.add_autodocumenter(AccessorCallableDocumenter)
     app.add_directive("autosummary", PandasAutosummary)
+
+    if os.environ.get("SPHINX_SKIP_IPYTHON"):
+        # override the directive
+        app.add_directive("ipython", SkipIPython)

doc/source/development/contributing.rst

@@ -595,6 +595,9 @@ reducing the turn-around time for checking your changes.
     python make.py clean
     python make.py --no-api
 
+    # skip executing the code blocks
+    python make.py --no-ipython
+
     # compile the docs with only a single section, relative to the "source" folder.
     # For example, compiling only this guide (doc/source/development/contributing.rst)
     python make.py clean