Skip to content

[DOC/BUILD] add ability to selectively build docs #24906

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
jklymak opened this issue Jan 7, 2023 · 2 comments · Fixed by #24907
Closed

[DOC/BUILD] add ability to selectively build docs #24906

jklymak opened this issue Jan 7, 2023 · 2 comments · Fixed by #24907
Labels
Documentation: build building the docs
Milestone
v3.8.0

Comments

@jklymak
Copy link
Member

jklymak commented Jan 7, 2023 •
edited
Loading

Looks like pandas’ approach is to loop through the docs and exclude everything except the one you ask for. This is in the conf.py and the make.py sets the relevant environment variable. So probably could be done with our existing make files - though a python make script might remove the need for separate Windows and Linux make files?

Originally posted by @rcomer in #24897 (comment)

Thanks @rcomer - something like that seems like it would be really helpful for us. I may play with it, but if anyone else w/ more sphinx experience wants to give it a shot, I think it'd be a pretty worthwhile project.
@jklymak jklymak added the Documentation: build building the docs label Jan 7, 2023
@jklymak
Copy link
Member Author

jklymak commented Jan 8, 2023

OK, I looked into this for a while. This is currently really easy to do in conf.py. After the initial gallery builds, doing

exclude_patterns = [
    'api/prev_api_changes/api_changes_*/*',
    'users/prev_whats_new/*',
    'gallery/*',
    'api/*',
    'tutorials/*',
    'plot_types/*',
    'devel/*'
]

means that you can build the docs in 5 seconds or so (on my machine). The first build is still really slow because it doesn't stop sphinx-gallery from running. If you further set example_dirs to an empty list, the whole build is super fast.

So I wonder if we should just document this for folks. I definitely didn't understand how exclude_patterns works, but now that I do, I'm not sure it's worth having a bunch of hooks or environment variables we check.

@jklymak jklymak mentioned this issue Jan 8, 2023
Merged
6 tasks
@rcomer
Copy link
Member

rcomer commented Jan 8, 2023 •
edited
Loading

The first build is still really slow because it doesn't stop sphinx-gallery from running.

What happens if you use this together with the make html-noplot option?

Edit: on second thoughts your approach of modifying example_dirs is clearly better as you might want the tutorials but not the gallery and plot types.

@QuLogic QuLogic added this to the v3.8.0 milestone Jan 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation: build building the docs
Projects
None yet
Milestone
v3.8.0
Development

Successfully merging a pull request may close this issue.

DOC/BUILD add ability for conf to skip whole sections jklymak/matplotlib
3 participants
@QuLogic @jklymak @rcomer