From 2541f23b7905323d1381ef20a30644a9d5c83662 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 12 Jan 2023 13:45:23 -0800 Subject: [PATCH] DOC/BUILD add ability for conf to skip whole sections --- .gitignore | 1 + doc/Makefile | 7 ++++ doc/conf.py | 51 +++++++++++++++++++++++++-- doc/devel/documenting_mpl.rst | 6 ++++ doc/make.bat | 6 ++++ environment.yml | 1 + requirements/doc/doc-requirements.txt | 1 + 7 files changed, 70 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 7d0e549e0125..0b7970f88290 100644 --- 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 index 6316a5ca0407..5022e16b7117 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -33,6 +33,13 @@ html-noplot: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +# 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_sub_dirs=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). %: Makefile diff --git a/doc/conf.py b/doc/conf.py index 2b5bc9f2bb6f..003391dcab7d 100644 --- 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,6 +35,42 @@ # are we running circle CI? CIRCLECI = 'CIRCLECI' in os.environ + +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 directories are included in build.') + + return default_skip_subdirs + + +skip_subdirs = [] +# triggered via make html-skip-subdirs +if 'skip_sub_dirs=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/ sourceyear = datetime.utcfromtimestamp( @@ -80,9 +117,11 @@ ] exclude_patterns = [ - 'api/prev_api_changes/api_changes_*/*', + 'api/prev_api_changes/api_changes_*/*' ] +exclude_patterns += skip_subdirs + def _check_dependencies(): names = { @@ -174,15 +213,20 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, gallery_conf['image_srcset'] = [] return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs) +gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types'] + if f'{ed}/*' not in skip_subdirs] + +example_dirs = [f'../{gd}'.replace('gallery', 'examples') for gd in + gallery_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': ['../examples', '../tutorials', '../plot_types'], + '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 '', @@ -711,5 +755,6 @@ def setup(app): bld_type = 'dev' else: bld_type = 'rel' + app.add_config_value('skip_sub_dirs', 0, '') app.add_config_value('releaselevel', bld_type, 'env') app.connect('html-page-context', add_html_cache_busting, priority=1000) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index b814e67cd308..2dcd33b8c0d6 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -71,6 +71,12 @@ Other useful invocations include # save time. make html-noplot + # Build the html documentation, but skip specific subdirectories. If a gallery + # directory is skipped, the gallery images are not generated. The first + # time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited + # to add or remove subdirectories + make html-skip-subdirs + # Delete built files. May help if you get errors about missing paths or # broken links. make clean diff --git a/doc/make.bat b/doc/make.bat index aa6612f08eae..220523d74b60 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -29,6 +29,7 @@ if errorlevel 9009 ( if "%1" == "" goto help if "%1" == "html-noplot" goto html-noplot +if "%1" == "html-skip-subdirs" goto html-skip-subdirs if "%1" == "show" goto show %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% @@ -52,6 +53,11 @@ goto end %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -D plot_gallery=0 goto end +:html-skip-subdirs +%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -D skip_sub_dirs=1 +goto end + + :show python -m webbrowser -t "%~dp0\build\html\index.html" diff --git a/environment.yml b/environment.yml index 22cf6796ac5e..2de7fdd5def5 100644 --- a/environment.yml +++ b/environment.yml @@ -33,6 +33,7 @@ dependencies: - numpydoc>=0.8 - packaging - pydata-sphinx-theme + - pyyaml - sphinx>=1.8.1,!=2.0.0 - sphinx-copybutton - sphinx-gallery>=0.10 diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index f4db1699fc5c..899ca254edab 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -15,6 +15,7 @@ numpydoc>=1.0 packaging>=20 pydata-sphinx-theme>=0.12.0 mpl-sphinx-theme +pyyaml sphinxcontrib-svg2pdfconverter>=1.1.0 sphinx-gallery>=0.10 sphinx-copybutton pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy