The doc build is painfully slow. This gives devs an easy way to populateexclude_patterns inconf.py with subdirectories they do not want while they are doing development,and to not do the gallery builds if those subdirectories are excluded. Of course the resulting build is broken with dropped references etc, so the developer should putconf.py back to its pristine state, but this should be a handy tool.

Note to build just theuser subdirectory using this takes 5s on my machine (if I exclude theprev_whats_new).

Closes#24906

Behaviour:

The interface ismake html-skip-subdirs which calls$(SPHINXBUILD) -D skip_sub_dirs=1 -b html ....

It tries to readdoc/.mpl_skip_subdirs.yaml. If that does not exist, that file is created and looks like:

comment:For use with make html-skip-subdirsskip_subdirs:-users/prev_whats_new/*-api/*-gallery/*-tutorials/*-plot_types/*-devel/*

If all ofgallery/* (etc) is skipped, then sphinx-gallery does not get run on that subdirectory. OTOH if only subdirectories of it are skipped, then the whole gallery is run (only once though, if gallery not previously generated).

With the above default theusers/* directory is built in 5 seconds on my machine, in contrast to the full doc build that takes upwards of 10 minutes.

PR Checklist

Documentation and Tests

Has pytest style unit tests (andpytest passes)
Documentation is sphinx and numpydoc compliant (the docs shouldbuild without error).
New plotting related features are documented with examples.

Release Notes

New features are marked with a.. versionadded:: directive in the docstring and documented indoc/users/next_whats_new/
API changes are marked with a.. versionchanged:: directive in the docstring and documented indoc/api/next_api_changes/
Release notes conform with instructions innext_whats_new/README.rst ornext_api_changes/README.rst

jklymak added the Documentation: buildbuilding the docs label

Jan 8, 2023

Copy link

Member

story645 commentedJan 8, 2023

if this was gonna go in, any way to pass in the exclusions on the command line?

Copy link

MemberAuthor

jklymak commentedJan 8, 2023

I think via environment variables is the only way and that is pretty ugly. Even command line is pretty ugly with a bunch of excludes.

rcomer reviewed

Jan 8, 2023

View reviewed changes

doc/conf.py OutdatedShow resolvedHide resolved

Copy link

Member

rcomer commentedJan 8, 2023

I think via environment variables is the only way and that is pretty ugly. Even command line is pretty ugly with a bunch of excludes.

I’m wondering whether it would be easy or desirable to do it with some sort of config file that is git-ignored. Then you could set it to whatever you like for local building and not need to revert each time you push.

Downside would be that I guess it would persist when you check out some other branch. I would likely forget about it and get confused about what’s going on with my doc build…

Copy link

Member

story645 commentedJan 8, 2023

I would likely forget about it and get confused about what’s going on with my doc build…

could add a line to the conf printing excluded folders/files

Copy link

Member

rcomer commentedJan 8, 2023

I would likely forget about it and get confused about what’s going on with my doc build…
could add a line to the conf printing excluded folders/files

Possibly hard to spot amongst all the other output from the doc build?

Copy link

Member

story645 commentedJan 8, 2023•
edited
Loading

Possibly hard to spot amongst all the other output from the doc build?

I'd put it at the very top b/f the sphinx generated output, where there really isn't much:

also possibly add a space/ "SPHINX OUTPUT BEGINS NOW" header between these two sections.

Copy link

MemberAuthor

jklymak commentedJan 8, 2023

This commit adds amake html-skip-dirs option, andmake html goes back to a full build. Still have to edit theconf.py.

It would be pretty easy to add a config file for this, but I hesitate just because I don't quite understand how that actually is git ignored. Either we distribute an example config file, or we don't. If we don't, then adding it to the gitignore is fine, but then users need to make it themselves by hand. Is that what we want?

Copy link

Member

rcomer commentedJan 8, 2023

@jklymak fair point.

It occurs to me that the contributor could also just not stage theirconf.py changes. Though that for me would mean having to break thegit commit -a habit!

Copy link

MemberAuthor

jklymak commentedJan 8, 2023

I docommit -a all the time as well. But I'd dogit restore conf.py to get it back to its original state.

But I guess having the user make askip-dir.yml or something isn't very hard and could be in the comments of Makefile

eg.

skip_dirs: users/prev_whats_new/*   - gallery/*   - api/*   - tutorials/*   - plot_types/*   - devel/*

should work.

story645 reviewed

Jan 8, 2023

View reviewed changes

doc/conf.py OutdatedShow resolvedHide resolved

jklymak force-pushed thedoc-conf-with-shortcuts branch 3 times, most recently from00b53a6 to47ad4a2Compare

January 9, 2023 02:32

Copy link

MemberAuthor

jklymak commentedJan 9, 2023

OK, latest commit does this via a yaml.make html-skip-subdirs will makedoc/.mpl_skip_subdirs.yaml with a default minimal build. The user can add or subtract entries to this (including commenting things out). Or if they remove it, it will get generated again whenmake html-skip-subdirs is called. This is.gitignore-d

Copy link

Member

story645 commentedJan 9, 2023

Any chance you have a windows machine to update the make.bat? Otherwise thats a good first issue follow up. I think here it's gonna be basically the same command? )

Copy link

MemberAuthor

jklymak commentedJan 9, 2023

I just pushed a change to make.bat. No idea if it works ;-)

jklymak force-pushed thedoc-conf-with-shortcuts branch 3 times, most recently from8b612e5 tobcb08eaCompare

January 9, 2023 04:24

tacaswell added this to thev3.8.0 milestone

Jan 9, 2023

jklymak commented

Jan 9, 2023

View reviewed changes

environment.ymlShow resolvedHide resolved

jklymak force-pushed thedoc-conf-with-shortcuts branch from1290285 tode27da7Compare

January 11, 2023 21:18

Copy link

MemberAuthor

jklymak commentedJan 11, 2023

Rebased so all tests should pass.

I know folks are busy with the release, but I'll agitate for this one a bit. a) it's a huge convenience for folks who are just changing a small part of the docs and b) it's also not user-facing, so the interface need not be set in stone. I've updated the proposal in the description above.

tacaswell approved these changes

Jan 12, 2023

View reviewed changes

Copy link

Member

QuLogic commentedJan 12, 2023•
edited
Loading

As a note, one can set something inconf.py from thecommand line via -D setting=value. However, I believe that doing so would mean that you could not check that value within the file itself, and you would need to move the processing of the value to another extension.