Skip to content

Commit eaf3f9e

Browse files
anntzeranntzer
committed
Switch to makefile-based doc build.
1 parent 4ed9996 commit eaf3f9e

14 files changed

+103
-315
lines changed

‎.circleci/config.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ mpl-run: &mpl-install
6868

6969
doc-run: &doc-build
7070
name: Build documentation
71-
command: python make.py html
71+
command: make O=-W html
7272
working_directory: doc
7373

7474
doc-bundle-run: &doc-bundle

‎.gitignore

-3
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,6 @@ doc/gallery
6666
doc/tutorials
6767
doc/modules
6868
doc/pyplots/tex_demo.png
69-
doc/users/installing.rst
70-
doc/_static/depsy_badge.svg
71-
doc/_static/matplotlibrc
7269
lib/dateutil
7370
examples/*/*.pdf
7471
examples/*/*.png

‎INSTALL.rst

-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. The source of this document is INSTALL.rst. During the doc build process,
2-
.. this file is copied over to doc/users/installing.rst.
3-
.. Therefore, you must edit INSTALL.rst, *not* doc/users/installing.rst!
4-
51
.. _pip: https://pypi.python.org/pypi/pip/
62

73
==========
@@ -13,7 +9,6 @@ Installing
139
If you wish to contribute to the project, it's recommended you
1410
:ref:`install the latest development version<install_from_source>`.
1511

16-
1712
.. contents::
1813

1914
Installing an official release

‎doc-requirements.txt

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@
66
# Install the documentation requirements with:
77
# pip install -r doc-requirements.txt
88
#
9-
sphinx>=1.3,!=1.5.0
9+
sphinx>=1.3,!=1.5.0,!=1.6.4
1010
colorspacious
1111
ipython
1212
mock
13-
numpydoc
13+
numpydoc>=0.4
1414
pillow
1515
sphinx-gallery>=0.1.12

‎doc/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = matplotlib
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/README.txt

+4-36
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,13 @@
11
Matplotlib documentation
22
========================
33

4-
54
Building the documentation
65
--------------------------
76

8-
To build the documentation, you will need additional dependencies:
9-
10-
* Sphinx-1.3 or later (version 1.5.0 is not supported)
11-
* numpydoc 0.4 or later
12-
* IPython
13-
* mock
14-
* colorspacious
15-
* pillow
16-
* graphviz
17-
18-
All of these dependencies *except graphviz* can be installed through pip::
19-
20-
pip install -r ../doc-requirements.txt
21-
22-
or all of them via conda and pip::
23-
24-
conda install sphinx numpydoc ipython mock graphviz pillow \
25-
sphinx-gallery
26-
pip install colorspacious
27-
28-
To build the HTML documentation, type ``python make.py html`` in this
29-
directory. The top file of the results will be ./build/html/index.html
30-
31-
**Note that Sphinx uses the installed version of the package to build the
32-
documentation**: Matplotlib must be installed *before* the docs can be
33-
generated.
34-
35-
You can build the documentation with several options:
36-
37-
* `--small` saves figures in low resolution.
38-
* `--allowsphinxwarnings`: Don't turn Sphinx warnings into errors.
39-
* `-n N` enables parallel build of the documentation using N process.
7+
See :file:`doc/devel/documenting_mpl.rst` for instructions to build the docs.
408

419
Organization
42-
-------------
10+
------------
4311

4412
This is the top level build directory for the Matplotlib
4513
documentation. All of the documentation is written using sphinx, a
@@ -57,12 +25,12 @@ python documentation system built on top of ReST. This directory contains
5725
* mpl_toolkits - documentation of individual toolkits that ship with
5826
Matplotlib
5927

60-
* make.py - the build script to build the html or PDF docs
61-
6228
* index.rst - the top level include document for Matplotlib docs
6329

6430
* conf.py - the sphinx configuration
6531

32+
* Makefile and make.bat - entry points for building the docs
33+
6634
* _static - used by the sphinx build system
6735

6836
* _templates - used by the sphinx build system

‎doc/_static/depsy_badge_default.svg

-1
This file was deleted.

‎doc/_templates/badgesidebar.html

-6
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,6 @@
44

55
<br/>
66

7-
<a href="http://depsy.org/package/python/matplotlib">
8-
<img src="{{ pathto('_static/depsy_badge.svg', 1) }}">
9-
</a>
10-
11-
<br/>
12-
137
Travis-CI: <a href="https://travis-ci.org/matplotlib/matplotlib">
148
<img src="https://travis-ci.org/matplotlib/matplotlib.svg?branch=master"/>
159
</a>

‎doc/devel/documenting_mpl.rst

+36-24
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,14 @@ the Sphinx_ documentation generation tool. There are several extra
1515
requirements that are needed to build the documentation. They are listed in
1616
:file:`doc-requirements.txt` as well as listed below:
1717

18-
1. Sphinx 1.3 or later (1.5.0 is not supported)
19-
2. numpydoc 0.4 or later
20-
3. IPython
21-
4. mock
22-
5. colorspacious
23-
6. Pillow
24-
7. Graphviz
18+
* Sphinx>=1.3, !=1.5.0, !=1.6.4
19+
* colorspacious
20+
* IPython
21+
* mock
22+
* numpydoc>=0.4
23+
* Pillow
24+
* sphinx-gallery>=0.1.12
25+
* graphviz
2526

2627
.. note::
2728

@@ -39,12 +40,12 @@ Sphinx_.
3940

4041
.. note::
4142

42-
An exception to this are the directories :file:`gallery` and
43-
:file:`tutorials`, which exist in the root directory. These contain Python
44-
files that are built by `Sphinx Gallery`_. When the docs are built,
45-
directories of the same name will be generated inside of :file:`docs/`. The
46-
generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be
47-
safely deleted.
43+
An exception to this are the directories :file:`gallery` and
44+
:file:`tutorials`, which exist in the root directory. These contain Python
45+
files that are built by `Sphinx Gallery`_. When the docs are built,
46+
directories of the same name will be generated inside of :file:`docs/`. The
47+
generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be
48+
safely deleted.
4849

4950
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
5051
directories Sphinx parses, how the docs are built, and how the extensions are
@@ -55,23 +56,34 @@ Building the docs
5556

5657
The documentation sources are found in the :file:`doc/` directory in
5758
the trunk. To build the users guide in html format, cd into
58-
:file:`doc/` and do:
59+
:file:`doc/` and run
5960

6061
.. code-block:: sh
6162
62-
python make.py html
63+
make html
6364
64-
The list of comamnds and flags for ``make.py`` can be listed by running
65-
``python make.py --help``. In particular,
65+
Other useful invocations include
6666

67-
* ``python make.py clean`` will delete the built Sphinx files. Use this
68-
command if you're getting strange errors about missing paths or broken links,
69-
particularly if you move files around.
70-
* ``python make.py latex`` builds a PDF of the documentation.
71-
* The ``--allowsphinxwarnings`` flag allows the docs to continue building even
72-
if Sphinx throws a warning. This is useful for debugging and spot-checking
73-
many warnings at once.
67+
.. code:: sh
7468
69+
# Delete built files. May help if you get errors about missing paths or
70+
# broken links.
71+
make clean
72+
73+
# Build pdf docs.
74+
make latexpdf
75+
76+
You can build the documentation with several options:
77+
78+
* ``make O=-W html`` turns Sphinx warnings into errors. The continuous
79+
integration script uses this option.
80+
* ``make O=-j4 html`` (for example) runs a parallel build with 4 processes.
81+
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
82+
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
83+
84+
Multiple options can be combined using e.g. ``make O='-W -j4 ...' html``. On
85+
Windows, the option needs to be set as the ``SPHINXOPTS`` environment
86+
variable, e.g. ``set SPHINXOPTS=-W -j4 & make html``.
7587

7688
Organization of Matplotlib's documentation
7789
==========================================

‎doc/devel/release_guide.rst

+2-4
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,7 @@ by merging all files in :file:`doc/users/next_whats_new/` coherently. Also,
5353
temporarily comment out the include and toctree glob; re-instate these after a
5454
release. Finally, make sure that the docs build cleanly ::
5555

56-
pushd doc
57-
python make.py html latex -n 16
58-
popd
56+
make -Cdoc O=-n$(nproc) html latexpdf
5957

6058
After the docs are built, check that all of the links, internal and external, are still
6159
valid. We use ``linkchecker`` for this, which has not been ported to python3 yet. You will
@@ -214,7 +212,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is::
214212
git checkout v2.0.0-doc
215213
git clean -xfd
216214
cd doc
217-
python make.py html latex -n 16
215+
make O=-n$(nproc) html latexpdf
218216

219217
which will build both the html and pdf version of the documentation.
220218

‎doc/make.bat

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=python -msphinx
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=build
12+
set SPHINXPROJ=matplotlib
13+
14+
%SPHINXBUILD% >NUL 2>NUL
15+
if errorlevel 9009 (
16+
echo.
17+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
18+
echo.then set the SPHINXBUILD environment variable to point to the full
19+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
20+
echo.Sphinx directory to PATH.
21+
echo.
22+
echo.If you don't have Sphinx installed, grab it from
23+
echo.http://sphinx-doc.org/
24+
exit /b 1
25+
)
26+
27+
if "%1" == "" goto help
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

0 commit comments

Comments
 (0)