Skip to content

Commit 51126eb

Browse files
Add html-noplot recipe to doc/Makefile (#1468)
* DOC: Add html-noplot recipe to doc/Makefile And we also tweak `make view` so that the built documentation opens regardless of whether it was built with make html or make html-noplot * FIX: Pin sphinx-gallery in MNE-BIDS doc/conf.py we have: ``` sphinx_gallery_conf["within_subsection_order"] = "mne_bids.utils._example_sorter" ``` But AFAICT this functionality wasn't workign prior to sphinx-gallery/sphinx-gallery#1391 , which was included in the release of sphinx-agallery v0.19 (released Feb 12 2025). https://sphinx-gallery.github.io/stable/changes.html#v0-19-0 Given that v0.19 was released less than 1 year ago, I think it is reasonable to assume that devs/contributors might have a sphinx-gallery version < 0.19 installed locally, in which case building the mne-bids docuemntation will fail, but the reason/solution won't be explicit. So I think that it is best to be explicit about the minimum required sphinx-gallery version we require to be able to successfully build our docs.
1 parent 9c550e1 commit 51126eb

File tree

2 files changed

+14
-3
lines changed

2 files changed

+14
-3
lines changed

doc/Makefile

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,22 @@ help:
1818
# Catch-all target: route all unknown targets to Sphinx using the new
1919
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
2020
%: Makefile
21-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(O)
22+
23+
# Build without executing the example gallery (faster)
24+
html-noplot:
25+
@$(SPHINXBUILD) $(SPHINXOPTS) -D plot_gallery=0 $(SOURCEDIR) $(BUILDDIR)
2226

2327
# View the built documentation
28+
# If we build the example gallery, the index file is at _build/html/index.html
29+
# If we don't (e.g. html-noplot), then it is at _build/index.html
2430
view:
25-
@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"
31+
@if [ -f "$(BUILDDIR)/html/index.html" ]; then \
32+
python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/$(BUILDDIR)/html/index.html')"; \
33+
elif [ -f "$(BUILDDIR)/index.html" ]; then \
34+
python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/$(BUILDDIR)/index.html')"; \
35+
else echo "No index.html file found to open. Did you build the docs?"; \
36+
fi
2637

2738
clean:
2839
-rm -rf _build auto_examples generated

pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ doc = [
5858
"seaborn",
5959
"sphinx-copybutton",
6060
"sphinx>=7.4.7",
61-
"sphinx_gallery",
61+
"sphinx_gallery>=0.19.0",
6262
]
6363
# Dependencies for using all mne_bids features
6464
full = [

0 commit comments

Comments
 (0)