Reduce amount of unnecessary recompilation done by sphinx

ezyang · ezyang · commit 740c3a6c3db0 · 2020-06-29T16:47:44.000-04:00
- Don't clean before running html-noplot (if you want to do a clean
  build, just run make clean yourself!)
- Replace filename_pattern with ignore_pattern (with a negative
  lookahead assertion).  This means that specifying a GALLERY_PATTERN
  will also skip parsing all Python files that you don't care about.
  This saves several seconds from the no-op doc build.
- Use distutils to only copy rst files if the mtime is newer than the
  destination; this (probably) helps Sphinx avoid recompiling these
  files when it's useless.

There are some semantic changes in this diff which is why I'm putting
it up for review.

Signed-off-by: Edward Z. Yang &lt;ezyang@fb.com&gt;
diff --git a/Makefile b/Makefile
@@ -108,7 +108,6 @@ docs:
 	touch docs/.nojekyll
 
 html-noplot:
-	make clean
 	$(SPHINXBUILD) -D plot_gallery=0 -b html $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
 	# bash .jenkins/remove_invisible_code_block_batch.sh "$(BUILDDIR)/html"
 	@echo
diff --git a/conf.py b/conf.py
@@ -35,6 +35,8 @@
 import glob
 import shutil
 from custom_directives import IncludeDirective, GalleryItemDirective, CustomGalleryItemDirective, CustomCalloutItemDirective, CustomCardItemDirective
+import distutils.file_util
+import re
 
 
 try:
@@ -63,10 +65,19 @@
     'examples_dirs': ['beginner_source', 'intermediate_source',
                       'advanced_source', 'recipes_source'],
     'gallery_dirs': ['beginner', 'intermediate', 'advanced', 'recipes'],
-    'filename_pattern': os.environ.get('GALLERY_PATTERN', r'tutorial.py'),
     'backreferences_dir': False
 }
 
+if os.getenv('GALLERY_PATTERN'):
+    # GALLERY_PATTERN is to be used when you want to work on a single
+    # tutorial.  Previously this was fed into filename_pattern, but
+    # if you do that, you still end up parsing all of the other Python
+    # files which takes a few seconds.  This strategy is better, as
+    # ignore_pattern also skips parsing.
+    # See https://github.com/sphinx-gallery/sphinx-gallery/issues/721
+    # for a more detailed description of the issue.
+    sphinx_gallery_conf['ignore_pattern'] = r'/(?!' + re.escape(os.getenv('GALLERY_PATTERN')) + r')[^/]+$'
+
 for i in range(len(sphinx_gallery_conf['examples_dirs'])):
     gallery_dir = sphinx_gallery_conf['gallery_dirs'][i]
     source_dir = sphinx_gallery_conf['examples_dirs'][i]
@@ -78,7 +89,7 @@
 
     # Copy rst files from source dir to gallery dir
     for f in glob.glob(os.path.join(source_dir, '*.rst')):
-        shutil.copy(f, gallery_dir)
+        distutils.file_util.copy_file(f, gallery_dir, update=True)
 
 
 # Add any paths that contain templates here, relative to this directory.
