docs: optimise building with html-tutorial support (#1146)

* docs: optimise building with html-tutorial support

* add changelog news fragment

changelog/1146.contributor.rst

@@ -0,0 +1,5 @@
+Optimised the documentation building workflow by providing control of whether
+:ref:`tutorial <gv-tutorials>` ``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`)

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.

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

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