Skip to content

Commit 75ff17a

Browse files
OriolAbrilOriolAbril
authored
speed-up doc building and fix several issues (#6781)
* speed-up doc building and fix several issues * undo misc page * try making censored/truncated/simulator nicer * fix methods rubric * fix ref to hide notebook cells
1 parent 77f24d7 commit 75ff17a

29 files changed

+200
-473
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ tags
1717

1818
# Sphinx
1919
_build
20+
docs/_build
21+
docs/build
2022
docs/jupyter_execute
2123
docs/.jupyter_cache
2224
docs/**/generated/*

‎.readthedocs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,6 @@ conda:
1212
environment: "conda-envs/environment-docs.yml"
1313

1414
build:
15-
os: "ubuntu-20.04"
15+
os: "ubuntu-22.04"
1616
tools:
1717
python: "mambaforge-4.10"

‎Makefile

+12-170
Original file line numberDiff line numberDiff line change
@@ -2,53 +2,25 @@
22
#
33

44
# You can set these variables from the command line.
5-
SPHINXOPTS =
65
SPHINXBUILD = sphinx-build
7-
PAPER =
86
SOURCEDIR = docs/source
9-
BUILDDIR = docs/_build
7+
BUILDDIR = docs/build
8+
9+
rtd: export READTHEDOCS=true
1010

1111
# User-friendly check for sphinx-build
1212
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
1313
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
1414
endif
1515

16-
# Internal variables.
17-
PAPEROPT_a4 = -D latex_paper_size=a4
18-
PAPEROPT_letter = -D latex_paper_size=letter
19-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
20-
# the i18n builder cannot share the environment and doctrees with the others
21-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
22-
23-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
16+
.PHONY: help clean html rtd view
2417

2518
help:
2619
@echo "Please use \`make <target>' where <target> is one of"
2720
@echo " html to make standalone HTML files"
28-
@echo " dirhtml to make HTML files named index.html in directories"
29-
@echo " singlehtml to make a single large HTML file"
30-
@echo " pickle to make pickle files"
31-
@echo " json to make JSON files"
32-
@echo " htmlhelp to make HTML files and a HTML help project"
33-
@echo " qthelp to make HTML files and a qthelp project"
34-
@echo " applehelp to make an Apple Help Book"
35-
@echo " devhelp to make HTML files and a Devhelp project"
36-
@echo " epub to make an epub"
37-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
38-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
39-
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
40-
@echo " text to make text files"
41-
@echo " man to make manual pages"
42-
@echo " texinfo to make Texinfo files"
43-
@echo " info to make Texinfo files and run them through makeinfo"
44-
@echo " gettext to make PO message catalogs"
45-
@echo " changes to make an overview of all changed/added/deprecated items"
46-
@echo " xml to make Docutils-native XML files"
47-
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
48-
@echo " linkcheck to check all external links for integrity"
49-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
50-
@echo " coverage to run coverage check of the documentation (if enabled)"
51-
@echo " serve to launch a server from built html files"
21+
@echo " rtd to build the website without any cache"
22+
@echo " clean to clean cache and intermediate files"
23+
@echo " view to open the built html files"
5224

5325
clean:
5426
rm -rf $(BUILDDIR)/*
@@ -62,140 +34,10 @@ html:
6234
@echo
6335
@echo "Build finished. The HTML pages are in $(BUILDDIR)."
6436

65-
dirhtml:
66-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
67-
@echo
68-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
69-
70-
singlehtml:
71-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
72-
@echo
73-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
74-
75-
pickle:
76-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
77-
@echo
78-
@echo "Build finished; now you can process the pickle files."
79-
80-
json:
81-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
82-
@echo
83-
@echo "Build finished; now you can process the JSON files."
84-
85-
htmlhelp:
86-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
87-
@echo
88-
@echo "Build finished; now you can run HTML Help Workshop with the" \
89-
".hhp project file in $(BUILDDIR)/htmlhelp."
90-
91-
qthelp:
92-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
93-
@echo
94-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
95-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
96-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pymc.qhcp"
97-
@echo "To view the help file:"
98-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pymc.qhc"
99-
100-
applehelp:
101-
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
102-
@echo
103-
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
104-
@echo "N.B. You won't be able to view it unless you put it in" \
105-
"~/Library/Documentation/Help or install it in your application" \
106-
"bundle."
107-
108-
devhelp:
109-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
110-
@echo
111-
@echo "Build finished."
112-
@echo "To view the help file:"
113-
@echo "# mkdir -p $$HOME/.local/share/devhelp/pymc"
114-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pymc"
115-
@echo "# devhelp"
116-
117-
epub:
118-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
119-
@echo
120-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
121-
122-
latex:
123-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
124-
@echo
125-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
126-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
127-
"(use \`make latexpdf' here to do that automatically)."
128-
129-
latexpdf:
130-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
131-
@echo "Running LaTeX files through pdflatex..."
132-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
133-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
134-
135-
latexpdfja:
136-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
137-
@echo "Running LaTeX files through platex and dvipdfmx..."
138-
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
139-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
140-
141-
text:
142-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
37+
rtd: clean
38+
$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html -E
14339
@echo
144-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
145-
146-
man:
147-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
148-
@echo
149-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
150-
151-
texinfo:
152-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
153-
@echo
154-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
155-
@echo "Run \`make' in that directory to run these through makeinfo" \
156-
"(use \`make info' here to do that automatically)."
157-
158-
info:
159-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
160-
@echo "Running Texinfo files through makeinfo..."
161-
make -C $(BUILDDIR)/texinfo info
162-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
163-
164-
gettext:
165-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
166-
@echo
167-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
168-
169-
changes:
170-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
171-
@echo
172-
@echo "The overview file is in $(BUILDDIR)/changes."
173-
174-
linkcheck:
175-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
176-
@echo
177-
@echo "Link check complete; look for any errors in the above output " \
178-
"or in $(BUILDDIR)/linkcheck/output.txt."
179-
180-
doctest:
181-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
182-
@echo "Testing of doctests in the sources finished, look at the " \
183-
"results in $(BUILDDIR)/doctest/output.txt."
184-
185-
coverage:
186-
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
187-
@echo "Testing of coverage in the sources finished, look at the " \
188-
"results in $(BUILDDIR)/coverage/python.txt."
189-
190-
xml:
191-
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
192-
@echo
193-
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
194-
195-
pseudoxml:
196-
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
197-
@echo
198-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
40+
@echo "Build finished. The HTML pages are in $(BUILDDIR)."
19941

200-
serve: html
201-
python -m http.server --directory $(BUILDDIR)
42+
view:
43+
python -m webbrowser $(BUILDDIR)/index.html

0 commit comments

Comments
 (0)