diff --git a/doc/make.py b/doc/make.py index d90cd2428360d..73c3d2370bf37 100755 --- a/doc/make.py +++ b/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, diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f7ddd8209272..c1dbd816d4f22 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,6 +17,7 @@ import os import sys +from IPython.sphinxext.ipython_directive import IPythonDirective import jinja2 from numpydoc.docscrape import NumpyDocString from sphinx.ext.autosummary import _import_by_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) diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst index 90ecee8cf9312..0e5c35bb3b797 100644 --- a/doc/source/development/contributing.rst +++ b/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