docs: Add ways to avoid building examples (#1321)

You can now run `make html-noplot` to build the docs without building
the examples.

Closes #1247

- Add Makefile target to avoid building examples
- Add redundant option in `sphinx/conf.py` to guide contributors
- Add documentation

CONTRIBUTING.rst

@@ -172,6 +172,16 @@ Then, you can access the local build via:
 
 The PR will also build the documentation and a bot will automatically add a comment with a link to the documentation preview to easily check the results.
 
+Skipping examples when building the docs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The examples can take a long time to build, so if you are not working on them you can instead run `make html-noplot` to avoid building them altogether.
+
+If you are working on an example and wish to only build that one, you can do so by temporarily editing `sphinx/conf.py`. Follow `the sphinx-gallery documentation https://sphinx-gallery.github.io/stable/configuration.html#parsing-and-executing-examples-via-matching-patterns` for more information.
+By default, the examples that are built are Python files that start with `plot_`.
+
+Note that by default, if an example has not changed since the last time you built it, it will not be re-built.
+
 Contributing to the docstrings
 ------------------------------
 

sphinx/Makefile

@@ -17,6 +17,11 @@ SPHINXBUILD ?= sphinx-build
 SOURCEDIR   = .
 BUILDDIR    = build
 
+# Build the docs without the examples, which can take a long time to run
+# From https://sphinx-gallery.github.io/stable/advanced.html#id4
+html-noplot:
+	@$(SPHINXBUILD) --builder html --define plot_gallery=0 "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sphinx/conf.py

@@ -85,6 +85,7 @@ def reset_mpl(gallery_conf, fname):
 sphinx_gallery_conf = {
     "examples_dirs": "../examples",  # path to example scripts
     "gallery_dirs": "auto_examples",  # path to gallery generated output
+    "filename_pattern": "plot_",  # pattern to select examples; change this to only build some of the examples
     "subsection_order": ExplicitOrder(subsections_order),  # sorting gallery subsections
     # see https://sphinx-gallery.github.io/stable/configuration.html#sub-gallery-order
     "within_subsection_order": "ExampleTitleSortKey",  # See https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-examples for alternatives