[MRG] MAINT moving to modern way of building docs. #9402
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| # Makefile for Sphinx documentation | ||
| # | ||
|
|
||
| # You can set these variables from the command line. | ||
| SPHINXOPTS = | ||
| SPHINXBUILD ?= sphinx-build | ||
| PAPER = | ||
| BUILDDIR = build | ||
|
|
||
| # Internal variables. | ||
| PAPEROPT_a4 = -D latex_paper_size=a4 | ||
| PAPEROPT_letter = -D latex_paper_size=letter | ||
| ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | ||
|
|
||
| .PHONY: help clean html dirhtml pickle json latex latexpdf changes linkcheck doctest optipng | ||
|
|
||
| all: html | ||
|
|
||
| help: | ||
| @echo "Please use \`make <target>' where <target> is one of" | ||
| @echo " html to make standalone HTML files" | ||
| @echo " dirhtml to make HTML files named index.html in directories" | ||
| @echo " pickle to make pickle files" | ||
| @echo " json to make JSON files" | ||
| @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" | ||
| @echo " latexpdf to make LaTeX files and run them through pdflatex" | ||
| @echo " changes to make an overview of all changed/added/deprecated items" | ||
| @echo " linkcheck to check all external links for integrity" | ||
| @echo " doctest to run all doctests embedded in the documentation (if enabled)" | ||
|
|
||
| clean: | ||
| -rm -rf $(BUILDDIR)/* | ||
| -rm -rf gallery/ | ||
| -rm -rf tutorials/ | ||
| -rm -rf api/_as_gen/ | ||
| -rm -rf generated/* | ||
| -rm -rf modules/generated/* | ||
| -rm -rf _static/matplotlibrc | ||
| -rm -rf _templates/gallery.html | ||
| -rm -rf users/installing.rst | ||
|
|
||
| html: prepare | ||
| # These two lines make the build a bit more lengthy, and the | ||
| # the embedding of images more robust | ||
| rm -rf $(BUILDDIR)/html/_images | ||
| #rm -rf _build/doctrees/ | ||
| $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) -W $(BUILDDIR)/html | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/html" | ||
|
|
||
|
|
||
| html-allow-warnings: prepare | ||
| # These two lines make the build a bit more lengthy, and the | ||
| # the embedding of images more robust | ||
| rm -rf $(BUILDDIR)/html/_images | ||
| #rm -rf _build/doctrees/ | ||
| $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/html" | ||
|
|
||
|
|
||
| html-noplot: prepare | ||
| $(SPHINXBUILD) -D plot_gallery=0 -b html -W $(ALLSPHINXOPTS) $(BUILDDIR)/html | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." | ||
|
|
||
| dirhtml: prepare | ||
| $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml | ||
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." | ||
|
|
||
| pickle: prepare | ||
| $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle | ||
| @echo | ||
| @echo "Build finished; now you can process the pickle files." | ||
|
|
||
| json: prepare | ||
| $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json | ||
| @echo | ||
| @echo "Build finished; now you can process the JSON files." | ||
|
|
||
| latex: prepare | ||
| $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| @echo | ||
| @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." | ||
| @echo "Run \`make' in that directory to run these through (pdf)latex" \ | ||
| "(use \`make latexpdf' here to do that automatically)." | ||
|
|
||
| latexpdf: prepare | ||
| $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| @echo "Running LaTeX files through pdflatex..." | ||
| make -C $(BUILDDIR)/latex all-pdf | ||
| @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." | ||
|
|
||
| changes: prepare | ||
| $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes | ||
| @echo | ||
| @echo "The overview file is in $(BUILDDIR)/changes." | ||
|
|
||
| linkcheck: prepare | ||
| $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | ||
| @echo | ||
| @echo "Link check complete; look for any errors in the above output " \ | ||
| "or in $(BUILDDIR)/linkcheck/output.txt." | ||
|
|
||
| doctest: prepare | ||
| $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest | ||
| @echo "Testing of doctests in the sources finished, look at the " \ | ||
| "results in $(BUILDDIR)/doctest/output.txt." | ||
|
|
||
| prepare: _static/matplotlibrc users/installing.rst | ||
|
|
||
| .SECONDARY: | ||
|
|
||
| ############################################# | ||
| # Matplotlib needs to copy paste stuff around | ||
| _static/matplotlibrc: ../lib/matplotlib/mpl-data/matplotlibrc | ||
| cp $< $@ | ||
|
|
||
| users/installing.rst: ../INSTALL.rst | ||
| cp $< $@ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why switch to conda? It looks like all we are using is python and then pip installing everything else.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I switch to conda only for the environment: we now need to access the scripts "sphinx-build", and not only the library as before. When installing with --user, we either need to change the PYTHONPATH manually, or use conda.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not just use
python -msphinxinstead? AFAIK sphinx-build is a strict synonym to it, except thatpython -msphinxlooks up PYTHONPATH (which is the same as what we did before in make.py) whereas sphinx-build uses PATH (which may be set differently).This relates to my earlier point about using the shorter/newer makefile generated by recent versions of sphinx.