Added Makefile rule to not build the examples (#3834)

.gitignore

@@ -9,9 +9,14 @@ torchvision/version.py
 */**/**/*.pyc
 */**/*~
 *~
+
 docs/build
+# sphinx-gallery
 docs/source/auto_examples/
 docs/source/gen_modules/
+# pytorch-sphinx-theme gets installed here
+docs/src
+
 .coverage
 htmlcov
 .*.swp

CONTRIBUTING.md

@@ -129,6 +129,24 @@ The docs are also automatically built when you submit a PR. The job that
 builds the docs is named `build_docs`. You can access the rendered docs by
 clicking on that job and then going to the "Artifacts" tab.
 
+You can clean the built docs and re-start the build from scratch by doing ``make
+clean``.
+
+#### Building the example gallery - or not
+
+When you run ``make html`` for the first time, all the examples in the gallery
+will be built. Subsequent builds should be faster, and will only build the
+examples that have been modified.
+
+You can run ``make html-noplot`` to not build the examples at all. This is
+useful after a ``make clean`` to do some quick checks that are not related to
+the examples.
+
+You can also choose to only build a subset of the examples by using the
+``EXAMPLES_PATTERN`` env variable, which accepts a regular expression. For
+example ``EXAMPLES_PATTERN="transforms" make html`` will only build the examples
+with "transforms" in their name.
+
 ### New model
 
 More details on how to add a new model will be provided later. Please, do not send any PR with a new model without discussing 

docs/Makefile

@@ -1,8 +1,12 @@
 # Minimal makefile for Sphinx documentation
 #
 
+ifneq ($(EXAMPLES_PATTERN),)
+    EXAMPLES_PATTERN_OPTS := -D sphinx_gallery_conf.filename_pattern="$(EXAMPLES_PATTERN)"
+endif
+
 # You can set these variables from the command line.
-SPHINXOPTS    = -W  # turn warnings into errors
+SPHINXOPTS    = -W -j auto $(EXAMPLES_PATTERN_OPTS)
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = torchvision
 SOURCEDIR     = source
@@ -20,13 +24,14 @@ docset: html
 	convert $(SPHINXPROJ).docset/icon@2x.png -resize 16x16 $(SPHINXPROJ).docset/icon.png
 
 html-noplot:  # Avoids running the gallery examples, which may take time
-	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ASPHINXOPTS)  "$(BUILDDIR)"/html
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ASPHINXOPTS) "${SOURCEDIR}" "$(BUILDDIR)"/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf $(SOURCEDIR)/auto_examples/
+	rm -rf $(SOURCEDIR)/auto_examples/  # sphinx-gallery
+	rm -rf $(SOURCEDIR)/gen_modules/  # sphinx-gallery
 
 .PHONY: help Makefile docset