Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 651a874

Browse filesBrowse files
jklymakjklymak
authored
Merge pull request #24907 from jklymak/doc-conf-with-shortcuts
DOC/BUILD add ability for conf to skip whole sections
2 parents 99d39bd + 2541f23 commit 651a874
Copy full SHA for 651a874

File tree

7 files changed

+70
-3
lines changed
Filter options

7 files changed

+70
-3
lines changed

‎.gitignore

Copy file name to clipboardExpand all lines: .gitignore
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ examples/tests/*
8282
!examples/tests/backend_driver_sgskip.py
8383
result_images
8484
doc/_static/constrained_layout*.png
85+
doc/.mpl_skip_subdirs.yaml
8586

8687
# Nose/Pytest generated files #
8788
###############################

‎doc/Makefile

Copy file name to clipboardExpand all lines: doc/Makefile
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,13 @@ html-noplot:
3333
@echo
3434
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
3535

36+
# This will skip the subdirectories listed in .mpl_skip_subdirs.yaml If
37+
# this file does not exist, one will be created for you. This option useful
38+
# to quickly build parts of the docs, but the resulting build will not
39+
# have all the crosslinks etc.
40+
html-skip-subdirs:
41+
$(SPHINXBUILD) -D skip_sub_dirs=1 -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
42+
3643
# Catch-all target: route all unknown targets to Sphinx using the new
3744
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
3845
%: Makefile

‎doc/conf.py

Copy file name to clipboardExpand all lines: doc/conf.py
+48-3Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import sys
2020
from urllib.parse import urlsplit, urlunsplit
2121
import warnings
22+
import yaml
2223

2324
import matplotlib
2425

@@ -34,6 +35,42 @@
3435
# are we running circle CI?
3536
CIRCLECI = 'CIRCLECI' in os.environ
3637

38+
39+
def _parse_skip_subdirs_file():
40+
"""
41+
Read .mpl_skip_subdirs.yaml for subdirectories to not
42+
build if we do `make html-skip-subdirs`. Subdirectories
43+
are relative to the toplevel directory. Note that you
44+
cannot skip 'users' as it contains the table of contents,
45+
but you can skip subdirectories of 'users'. Doing this
46+
can make partial builds very fast.
47+
"""
48+
default_skip_subdirs = ['users/prev_whats_new/*', 'api/*', 'gallery/*',
49+
'tutorials/*', 'plot_types/*', 'devel/*']
50+
try:
51+
with open(".mpl_skip_subdirs.yaml", 'r') as fin:
52+
print('Reading subdirectories to skip from',
53+
'.mpl_skip_subdirs.yaml')
54+
out = yaml.full_load(fin)
55+
return out['skip_subdirs']
56+
except FileNotFoundError:
57+
# make a default:
58+
with open(".mpl_skip_subdirs.yaml", 'w') as fout:
59+
yamldict = {'skip_subdirs': default_skip_subdirs,
60+
'comment': 'For use with make html-skip-subdirs'}
61+
yaml.dump(yamldict, fout)
62+
print('Skipping subdirectories, but .mpl_skip_subdirs.yaml',
63+
'not found so creating a default one. Edit this file',
64+
'to customize which directories are included in build.')
65+
66+
return default_skip_subdirs
67+
68+
69+
skip_subdirs = []
70+
# triggered via make html-skip-subdirs
71+
if 'skip_sub_dirs=1' in sys.argv:
72+
skip_subdirs = _parse_skip_subdirs_file()
73+
3774
# Parse year using SOURCE_DATE_EPOCH, falling back to current time.
3875
# https://reproducible-builds.org/specs/source-date-epoch/
3976
sourceyear = datetime.utcfromtimestamp(
@@ -80,9 +117,11 @@
80117
]
81118

82119
exclude_patterns = [
83-
'api/prev_api_changes/api_changes_*/*',
120+
'api/prev_api_changes/api_changes_*/*'
84121
]
85122

123+
exclude_patterns += skip_subdirs
124+
86125

87126
def _check_dependencies():
88127
names = {
@@ -174,15 +213,20 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
174213
gallery_conf['image_srcset'] = []
175214
return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
176215

216+
gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types']
217+
if f'{ed}/*' not in skip_subdirs]
218+
219+
example_dirs = [f'../{gd}'.replace('gallery', 'examples') for gd in
220+
gallery_dirs]
177221

178222
sphinx_gallery_conf = {
179223
'backreferences_dir': Path('api') / Path('_as_gen'),
180224
# Compression is a significant effort that we skip for local and CI builds.
181225
'compress_images': ('thumbnails', 'images') if is_release_build else (),
182226
'doc_module': ('matplotlib', 'mpl_toolkits'),
183-
'examples_dirs': ['../examples', '../tutorials', '../plot_types'],
227+
'examples_dirs': example_dirs,
184228
'filename_pattern': '^((?!sgskip).)*$',
185-
'gallery_dirs': ['gallery', 'tutorials', 'plot_types'],
229+
'gallery_dirs': gallery_dirs,
186230
'image_scrapers': (matplotlib_reduced_latex_scraper, ),
187231
'image_srcset': ["2x"],
188232
'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '',
@@ -711,5 +755,6 @@ def setup(app):
711755
bld_type = 'dev'
712756
else:
713757
bld_type = 'rel'
758+
app.add_config_value('skip_sub_dirs', 0, '')
714759
app.add_config_value('releaselevel', bld_type, 'env')
715760
app.connect('html-page-context', add_html_cache_busting, priority=1000)

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,12 @@ Other useful invocations include
7171
# save time.
7272
make html-noplot
7373
74+
# Build the html documentation, but skip specific subdirectories. If a gallery
75+
# directory is skipped, the gallery images are not generated. The first
76+
# time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
77+
# to add or remove subdirectories
78+
make html-skip-subdirs
79+
7480
# Delete built files. May help if you get errors about missing paths or
7581
# broken links.
7682
make clean

‎doc/make.bat

Copy file name to clipboardExpand all lines: doc/make.bat
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ if errorlevel 9009 (
2929

3030
if "%1" == "" goto help
3131
if "%1" == "html-noplot" goto html-noplot
32+
if "%1" == "html-skip-subdirs" goto html-skip-subdirs
3233
if "%1" == "show" goto show
3334

3435
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
@@ -52,6 +53,11 @@ goto end
5253
%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -D plot_gallery=0
5354
goto end
5455

56+
:html-skip-subdirs
57+
%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -D skip_sub_dirs=1
58+
goto end
59+
60+
5561
:show
5662
python -m webbrowser -t "%~dp0\build\html\index.html"
5763

‎environment.yml

Copy file name to clipboardExpand all lines: environment.yml
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ dependencies:
3333
- numpydoc>=0.8
3434
- packaging
3535
- pydata-sphinx-theme
36+
- pyyaml
3637
- sphinx>=1.8.1,!=2.0.0
3738
- sphinx-copybutton
3839
- sphinx-gallery>=0.10

‎requirements/doc/doc-requirements.txt

Copy file name to clipboardExpand all lines: requirements/doc/doc-requirements.txt
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ numpydoc>=1.0
1515
packaging>=20
1616
pydata-sphinx-theme>=0.12.0
1717
mpl-sphinx-theme
18+
pyyaml
1819
sphinxcontrib-svg2pdfconverter>=1.1.0
1920
sphinx-gallery>=0.10
2021
sphinx-copybutton

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.