Skip to content

Commit d31d33c

Browse files
larsonerlarsoner
committed
ENH: Switch to sphinx-gallery, add API page
1 parent 832e188 commit d31d33c

24 files changed

+439
-248
lines changed

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ build
99
dist/
1010
doc/_build/
1111
doc/build/
12-
doc/examples/
12+
doc/auto_examples/
13+
doc/generated/
1314
doc/example_data
1415
doc/modules/generated/
1516
doc/documentation/pysurfer_usage.txt

‎doc/Makefile

+65-80
Original file line numberDiff line numberDiff line change
@@ -3,130 +3,115 @@
33

44
# You can set these variables from the command line.
55
SPHINXOPTS =
6-
SPHINXBUILD = python `which sphinx-build`
6+
SPHINXBUILD = sphinx-build
77
PAPER =
8-
BUILDDIR = _build
98

109
# Internal variables.
1110
PAPEROPT_a4 = -D latex_paper_size=a4
1211
PAPEROPT_letter = -D latex_paper_size=letter
13-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14-
EXAMPLEDIR = examples
12+
ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
1513

16-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
14+
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
1715

1816
help:
1917
@echo "Please use \`make <target>' where <target> is one of"
20-
@echo " html to make standalone HTML files"
21-
@echo " dirhtml to make HTML files named index.html in directories"
22-
@echo " singlehtml to make a single large HTML file"
23-
@echo " pickle to make pickle files"
24-
@echo " json to make JSON files"
25-
@echo " htmlhelp to make HTML files and a HTML help project"
26-
@echo " qthelp to make HTML files and a qthelp project"
27-
@echo " devhelp to make HTML files and a Devhelp project"
28-
@echo " epub to make an epub"
29-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
30-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
31-
@echo " text to make text files"
32-
@echo " man to make manual pages"
33-
@echo " changes to make an overview of all changed/added/deprecated items"
34-
@echo " linkcheck to check all external links for integrity"
35-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
18+
@echo " html_stable to make standalone HTML files (stable version)"
19+
@echo " html_dev to make standalone HTML files (dev version)"
20+
@echo " html_dev-pattern to make standalone HTML files for one example dir (dev version)"
21+
@echo " *-noplot to make standalone HTML files without plotting"
22+
@echo " dirhtml to make HTML files named index.html in directories"
23+
@echo " pickle to make pickle files"
24+
@echo " json to make JSON files"
25+
@echo " htmlhelp to make HTML files and a HTML help project"
26+
@echo " qthelp to make HTML files and a qthelp project"
27+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
28+
@echo " changes to make an overview of all changed/added/deprecated items"
29+
@echo " linkcheck to check all external links for integrity"
30+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
3631

3732
clean:
38-
-rm -rf $(BUILDDIR)/* $(EXAMPLEDIR)/*
33+
-rm -rf _build/*
34+
-rm -rf auto_examples
35+
-rm -rf auto_tutorials
36+
-rm -rf generated
37+
-rm -rf *.stc
38+
-rm -rf *.fif
39+
-rm -rf *.nii.gz
40+
41+
html_stable:
42+
$(SPHINXBUILD) -D raise_gallery=1 -b html $(ALLSPHINXOPTS) _build/html_stable
43+
@echo
44+
@echo "Build finished. The HTML pages are in _build/html_stable."
3945

40-
html:
41-
../bin/pysurfer --help > documentation/pysurfer_usage.txt
42-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46+
html_dev:
47+
BUILD_DEV_HTML=1 $(SPHINXBUILD) -D raise_gallery=1 -D abort_on_example_error=1 -b html $(ALLSPHINXOPTS) _build/html
4348
@echo
44-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
49+
@echo "Build finished. The HTML pages are in _build/html"
4550

46-
dirhtml:
47-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51+
html_dev-pattern:
52+
BUILD_DEV_HTML=1 $(SPHINXBUILD) -D plot_gallery=1 -D raise_gallery=1 -D abort_on_example_error=1 -D sphinx_gallery_conf.filename_pattern=$(PATTERN) -b html $(ALLSPHINXOPTS) _build/html
53+
@echo
54+
@echo "Build finished. The HTML pages are in _build/html"
55+
56+
html_dev-noplot:
57+
BUILD_DEV_HTML=1 $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) _build/html
4858
@echo
49-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
59+
@echo "Build finished. The HTML pages are in _build/html."
5060

51-
singlehtml:
52-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
61+
dirhtml:
62+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
5363
@echo
54-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
64+
@echo "Build finished. The HTML pages are in _build/dirhtml."
5565

5666
pickle:
57-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
67+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
5868
@echo
5969
@echo "Build finished; now you can process the pickle files."
6070

6171
json:
62-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
72+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
6373
@echo
6474
@echo "Build finished; now you can process the JSON files."
6575

6676
htmlhelp:
67-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
77+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
6878
@echo
6979
@echo "Build finished; now you can run HTML Help Workshop with the" \
70-
".hhp project file in $(BUILDDIR)/htmlhelp."
80+
".hhp project file in _build/htmlhelp."
7181

7282
qthelp:
73-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
83+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
7484
@echo
7585
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
76-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
77-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PySurfer.qhcp"
78-
@echo "To view the help file:"
79-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PySurfer.qhc"
80-
81-
devhelp:
82-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
83-
@echo
84-
@echo "Build finished."
86+
".qhcp project file in _build/qthelp, like this:"
87+
@echo "# qcollectiongenerator _build/qthelp/MNE.qhcp"
8588
@echo "To view the help file:"
86-
@echo "# mkdir -p $$HOME/.local/share/devhelp/PySurfer"
87-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PySurfer"
88-
@echo "# devhelp"
89-
90-
epub:
91-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
92-
@echo
93-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
89+
@echo "# assistant -collectionFile _build/qthelp/MNE.qhc"
9490

9591
latex:
96-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
92+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
9793
@echo
98-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
99-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
100-
"(use \`make latexpdf' here to do that automatically)."
101-
102-
latexpdf:
103-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
104-
@echo "Running LaTeX files through pdflatex..."
105-
make -C $(BUILDDIR)/latex all-pdf
106-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
107-
108-
text:
109-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
110-
@echo
111-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
112-
113-
man:
114-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
115-
@echo
116-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
94+
@echo "Build finished; the LaTeX files are in _build/latex."
95+
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
96+
"run these through (pdf)latex."
11797

11898
changes:
119-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
99+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
120100
@echo
121-
@echo "The overview file is in $(BUILDDIR)/changes."
101+
@echo "The overview file is in _build/changes."
122102

123103
linkcheck:
124-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
104+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
125105
@echo
126106
@echo "Link check complete; look for any errors in the above output " \
127-
"or in $(BUILDDIR)/linkcheck/output.txt."
107+
"or in _build/linkcheck/output.txt."
128108

129109
doctest:
130-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
110+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
131111
@echo "Testing of doctests in the sources finished, look at the " \
132-
"results in $(BUILDDIR)/doctest/output.txt."
112+
"results in _build/doctest/output.txt."
113+
114+
view:
115+
@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"
116+
117+
show: view

‎doc/_static/banner.png

-3.09 KB
Loading

‎doc/_templates/class.rst

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{ fullname }}
2+
{{ underline }}
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autoclass:: {{ objname }}
7+
:special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__
8+
9+
{% block methods %}
10+
{% endblock %}
11+
12+

‎doc/_templates/function.rst

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{ fullname }}
2+
{{ underline }}
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autofunction:: {{ objname }}
7+
8+
.. include:: {{module}}.{{objname}}.examples
9+
10+
.. raw:: html
11+
12+
<div style='clear:both'></div>

‎doc/_templates/layout.html

-8
Original file line numberDiff line numberDiff line change
@@ -1,9 +1 @@
11
{% extends "!layout.html" %}
2-
{% set title = 'PySurfer Python Neuroimaging Visualization' %}
3-
4-
{% block header %}
5-
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
6-
<a href="{{pathto('index') }}">
7-
<img src="{{ pathto("_static/banner.png", 1) }}" alt="PySurfer logo" height=180px width=600px border="0" />
8-
</div>
9-
{% endblock %}

0 commit comments

Comments
 (0)