From 5bcb292df7f3b1d4d177654f447186ec3ba43ee3 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Wed, 9 Oct 2024 23:55:57 +0100 Subject: [PATCH] docs: optimise building with html-tutorial support (#1146) * docs: optimise building with html-tutorial support * add changelog news fragment --- changelog/1146.contributor.rst | 5 +++++ docs/Makefile | 13 ++++++++----- docs/src/conf.py | 31 ++++++++++++++++++++++++------- docs/src/tutorials/index.rst | 3 ++- 4 files changed, 39 insertions(+), 13 deletions(-) create mode 100644 changelog/1146.contributor.rst diff --git a/changelog/1146.contributor.rst b/changelog/1146.contributor.rst new file mode 100644 index 00000000..40399592 --- /dev/null +++ b/changelog/1146.contributor.rst @@ -0,0 +1,5 @@ +Optimised the documentation building workflow by providing control of whether +:ref:`tutorial ` ``jupyter notebook`` code cells are executed. +By default, code cells will only be executed when building the documentation +with either the ``make html`` or ``make html-tutorial`` commands. +(:user:`bjlittle`) diff --git a/docs/Makefile b/docs/Makefile index 6f278390..18656bb2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,7 +17,7 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: Makefile clean doctest help html-docstring html-gallery html-noplot linkcheck serve-html +.PHONY: Makefile clean doctest help html-docstring html-gallery html-noplot html-tutorial linkcheck serve-html clean: -rm -rf $(BUILDDIR) @@ -28,19 +28,22 @@ clean: -rm -f $(SOURCEDIR)/gallery_carousel.txt doctest: - @$(SPHINXBUILD) -b doctest -D plot_gallery=False -D plot_docstring=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/doctest" + @$(SPHINXBUILD) -b doctest -D plot_docstring=False -D plot_gallery=False -D plot_tutorial=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/doctest" html-docstring: - @$(SPHINXBUILD) -b html -D plot_gallery=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" + @$(SPHINXBUILD) -b html -D plot_gallery=False -D plot_tutorial=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" html-gallery: - @$(SPHINXBUILD) -b html -D plot_docstring=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" + @$(SPHINXBUILD) -b html -D plot_docstring=False -D plot_tutorial=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" html-noplot: + @$(SPHINXBUILD) -b html -D plot_docstring=False -D plot_gallery=False -D plot_tutorial=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" + +html-tutorial: @$(SPHINXBUILD) -b html -D plot_docstring=False -D plot_gallery=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" linkcheck: - @$(SPHINXBUILD) -b linkcheck -D plot_docstring=False -D plot_gallery=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" + @$(SPHINXBUILD) -b linkcheck -D plot_docstring=False -D plot_gallery=False -D plot_tutorial=False -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" # Spin up a local http server to view the rendered documentation. # This is required for interactive examples to work. diff --git a/docs/src/conf.py b/docs/src/conf.py index 57589fbe..a73aa0d6 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -766,13 +766,28 @@ def generate_carousel( Path(app.srcdir, fname).write_text(carousel) -def geovista_config(app: Sphinx) -> None: +def geovista_builder_inited(app: Sphinx) -> None: """Configure geovista sphinx options.""" - # sanitise the config options - app.builder.config.plot_docstring = _bool_eval(app.builder.config.plot_docstring) - autolog(f"plot_docstring={app.builder.config.plot_docstring}", section="GeoVista") + plot_docstring = _bool_eval(app.builder.config.plot_docstring) plot_gallery = _bool_eval(app.builder.config.plot_gallery) + plot_tutorial = _bool_eval(app.builder.config.plot_tutorial) + + # overwrite the myst-nb sphinx configuration option that controls the + # notebook execution mode. this option has been pre-parsed by the sphinx + # state machine from this file (conf.py) or set by the default myst-nb app + # configuration. for further details see + # https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html + if not plot_tutorial: + # https://myst-nb.readthedocs.io/en/latest/configuration.html#execution + app.config["nb_execution_mode"] = "off" + + # sanitise the config option from str to bool + app.builder.config.plot_docstring = plot_docstring + + # report diagnostics + autolog(f"{plot_docstring=}", section="GeoVista") autolog(f"{plot_gallery=}", section="GeoVista") + autolog(f"{plot_tutorial=}", section="GeoVista") def geovista_carousel( @@ -797,9 +812,11 @@ def setup(app: Sphinx) -> None: # we require the output of this extension app.setup_extension("sphinx_gallery.gen_gallery") # register geovista options - app.add_config_value("plot_docstring", "True", "html") - # early configuration of geovista options - app.connect("builder-inited", geovista_config, priority=10) + app.add_config_value(name="plot_docstring", default="True", rebuild="html") + app.add_config_value(name="plot_tutorial", default="True", rebuild="html") + # early configuration of geovista options, see + # https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html + app.connect("builder-inited", geovista_builder_inited, priority=10) # register callback for the autoapi event app.connect("autoapi-skip-member", geovista_skip_member) # register callback to generate gallery carousel diff --git a/docs/src/tutorials/index.rst b/docs/src/tutorials/index.rst index c1623fa4..da37a0ee 100644 --- a/docs/src/tutorials/index.rst +++ b/docs/src/tutorials/index.rst @@ -19,7 +19,8 @@ A collection of themed practical lessons to work though. .. grid-item-card:: :text-align: center - :link: region-manifold-extraction.html + :link: gv-tutorials-region-manifold-extraction + :link-type: ref .. image:: ../_static/images/region-manifold-extraction.png :alt: Region Manifold Extraction