Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: add option for skipping execution of code blocks #39360

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions doc/make.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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"
Expand Down Expand Up @@ -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,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is default needed with action="store_true"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure; I just copied from --no-api above.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

help="skip execution of code blocks",
action="store_true",
)
argparser.add_argument(
"--single",
metavar="FILENAME",
Expand Down Expand Up @@ -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,
Expand Down
15 changes: 15 additions & 0 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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)
3 changes: 3 additions & 0 deletions doc/source/development/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth noting why someone might do this - slight performance improvements :)

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
Expand Down