Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5392f2e

Browse files
tacaswelltacaswell
authored
Merge pull request #9513 from anntzer/make-docs
BLD: Switch to makefile-based doc build
2 parents 27090ee + b4b1f64 commit 5392f2e

14 files changed

+106
-310
lines changed

‎.circleci/config.yml

Lines changed: 1 addition & 1 deletion
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 html
7272
working_directory: doc
7373

7474
doc-bundle-run: &doc-bundle

‎.gitignore

Lines changed: 0 additions & 3 deletions
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

Lines changed: 0 additions & 5 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 20 additions & 0 deletions
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 = -W
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

Lines changed: 4 additions & 36 deletions
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

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎doc/_templates/badgesidebar.html

Lines changed: 0 additions & 6 deletions
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

Lines changed: 37 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,14 @@ the Sphinx_ documentation generation tool. There are several extra requirements
1515
that are needed to build the documentation. They are listed in
1616
:file:`doc-requirements.txt` and 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

@@ -69,24 +70,41 @@ Building the docs
6970
-----------------
7071

7172
The documentation sources are found in the :file:`doc/` directory in the trunk.
72-
To build the documentation in html format, cd into :file:`doc/` and run:
73+
To build the documentation in html format, cd into :file:`doc/` and run
7374

7475
.. code-block:: sh
7576
76-
python make.py html
77+
make html
7778
78-
The list of commands and flags for ``make.py`` can be listed by running
79-
``python make.py --help``. In particular,
79+
Other useful invocations include
8080

81-
* ``python make.py clean`` will delete the built Sphinx files. Use this command
82-
if you're getting strange errors about missing paths or broken links,
83-
particularly if you move files around.
84-
* ``python make.py latex`` builds a PDF of the documentation.
85-
* The ``--allowsphinxwarnings`` flag allows the docs to continue building even
86-
if Sphinx throws a warning. This is useful for debugging and spot-checking
87-
many warnings at once.
81+
.. code-block:: sh
82+
83+
# Delete built files. May help if you get errors about missing paths or
84+
# broken links.
85+
make clean
86+
87+
# Build pdf docs.
88+
make latexpdf
89+
90+
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
91+
errors. To unset it, use
92+
93+
.. code-block:: sh
94+
95+
make SPHINXOPTS= html
96+
97+
You can use the ``O`` variable to set additional options:
98+
99+
* ``make O=-j4 html`` runs a parallel build with 4 processes.
100+
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
101+
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
102+
103+
Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
104+
html``.
88105

89-
.. _formatting-mpl-docs:
106+
On Windows, options needs to be set as environment variables, e.g. ``set O=-W
107+
-j4 & make html``.
90108

91109
Writing new documentation
92110
=========================

‎doc/devel/release_guide.rst

Lines changed: 2 additions & 4 deletions
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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
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+
set SPHINXOPTS=-W
14+
set O=
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
20+
echo.then set the SPHINXBUILD environment variable to point to the full
21+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
22+
echo.Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
if "%1" == "" goto help
30+
31+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
32+
goto end
33+
34+
:help
35+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
36+
37+
:end
38+
popd

0 commit comments

Comments
 (0)