DOC/BUILD: make yaml version of skip list

jklymak · jklymak · commit 00b53a69402c · 2023-01-08T18:31:50.000-08:00
diff --git a/.gitignore b/.gitignore
@@ -82,6 +82,7 @@ examples/tests/*
 !examples/tests/backend_driver_sgskip.py
 result_images
 doc/_static/constrained_layout*.png
+doc/.mpl_skip_subdirs.yaml
 
 # Nose/Pytest generated files #
 ###############################
diff --git a/doc/Makefile b/doc/Makefile
@@ -33,12 +33,12 @@ html-noplot:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-# This will skip the directories listed in the skip_subdirs variable
-# in conf.py.  Edit this by hand if you want to change what sections
-# of the docs get built.  Can be much faster.  However, reset conf.py
-# to original values before pushig to github.
-html-skip-dirs:
-	$(SPHINXBUILD) -D skip_dirs=1 -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
+# This will skip the subdirectories listed in .mpl_skip_subdirs.yaml If
+# this file does not exist, one will be created for you.  This option useful
+# to quickly build parts of the docs, but the resulting build will not
+# have all the crosslinks etc.
+html-skip-subdirs:
+	$(SPHINXBUILD) -D skip_subdirs=1 -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
diff --git a/doc/conf.py b/doc/conf.py
@@ -19,6 +19,7 @@
 import sys
 from urllib.parse import urlsplit, urlunsplit
 import warnings
+import yaml
 
 import matplotlib
 
@@ -34,22 +35,41 @@
 # are we running circle CI?
 CIRCLECI = 'CIRCLECI' in os.environ
 
-# shortcuts: subdirectories to not build.  Should be relative
-# to the doc directory.  Note that you cannot skip "users"
-# but can skip subdirectories...
-#
-# Note if any of the sphinx-galleries are skipped then they
-# will not be built using sphinx-gallery.
+
+def _parse_skip_subdirs_file():
+    """
+    Read .mpl_skip_subdirs.yaml for subdirectories to not
+    build if we do `make html-skip-subdirs`.  Subdirectories
+    are relative to the toplevel directory.  Note that you
+    cannot skip 'users' as it contains the table of contents,
+    but you can skip subdirectories of 'users'.  Doing this
+    can make partial builds very fast.
+    """
+    default_skip_subdirs = ['users/prev_whats_new/*', 'api/*', 'gallery/*',
+                            'tutorials/*', 'plot_types/*', 'devel/*']
+    try:
+        with open(".mpl_skip_subdirs.yaml", 'r') as fin:
+            print('Reading subdirectories to skip from',
+                  '.mpl_skip_subdirs.yaml')
+            out = yaml.full_load(fin)
+        return out['skip_subdirs']
+    except FileNotFoundError:
+        # make a default:
+        with open(".mpl_skip_subdirs.yaml", 'w') as fout:
+            yamldict = {'skip_subdirs': default_skip_subdirs,
+                        'comment': 'For use with make html-skip-subdirs'}
+            yaml.dump(yamldict, fout)
+        print('Skipping subdirectories, but .mpl_skip_subdirs.yaml',
+              'not found so creating a default one. Edit this file',
+              'to customize which diretories are included in build.')
+
+        return default_skip_subdirs
+
+
 skip_subdirs = []
-if 'skip_dirs=1' in sys.argv:
-    skip_subdirs = [
-        'users/prev_whats_new/*',
-        'gallery/*',
-        'api/*',
-        'tutorials/*',
-        'plot_types/*',
-        'devel/*'
-    ]
+# triggered via make html-skip-subdirs
+if 'skip_subdirs=1' in sys.argv:
+    skip_subdirs = _parse_skip_subdirs_file()
 
 # Parse year using SOURCE_DATE_EPOCH, falling back to current time.
 # https://reproducible-builds.org/specs/source-date-epoch/
@@ -193,22 +213,23 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
         gallery_conf['image_srcset'] = []
     return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
 
-example_dirs = []
-if 'gallery/*' not in skip_subdirs:
-    example_dirs += ['../examples']
-if 'tutorials/*' not in skip_subdirs:
-    example_dirs += ['../tutorials']
-if 'plot_types/*' not in skip_subdirs:
-    example_dirs += ['../plot_types']
+example_dirs = [f'../{ed}' for ed in ['gallery', 'tutorials', 'plot_types']
+                if f'{ed}/*' not in skip_subdirs]
+example_dirs = ['../examples' if d == '../gallery' else d
+                for d in example_dirs]
+
+gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types']
+                if f'{ed}/*' not in skip_subdirs]
 
+print('EXAMPLES', example_dirs)
 sphinx_gallery_conf = {
     'backreferences_dir': Path('api') / Path('_as_gen'),
     # Compression is a significant effort that we skip for local and CI builds.
     'compress_images': ('thumbnails', 'images') if is_release_build else (),
     'doc_module': ('matplotlib', 'mpl_toolkits'),
     'examples_dirs': example_dirs,
     'filename_pattern': '^((?!sgskip).)*$',
-    'gallery_dirs': ['gallery', 'tutorials', 'plot_types'],
+    'gallery_dirs': gallery_dirs,
     'image_scrapers': (matplotlib_reduced_latex_scraper, ),
     'image_srcset': ["2x"],
     'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '',
@@ -737,6 +758,6 @@ def setup(app):
         bld_type = 'dev'
     else:
         bld_type = 'rel'
-    app.add_config_value('skip_dirs', 0, '')
+    app.add_config_value('skip_subdirs', 0, '')
     app.add_config_value('releaselevel', bld_type, 'env')
     app.connect('html-page-context', add_html_cache_busting, priority=1000)
