diff --git a/.gitignore b/.gitignore index ed35abaa478..3a1e8b6232a 100644 --- a/.gitignore +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14161dfbd81..71dde22c6a6 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index de809ed81cb..0488c3db88f 100644 --- a/docs/Makefile +++ b/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