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

Skip to content

Commit 7e8ccbc

Browse files
anntzeranntzer
committed
Switch to makefile-based doc build.
1 parent 0e3dd2d commit 7e8ccbc

14 files changed

+102
-319
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 O=-W 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 =
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: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@ are needed to build the documentation. They are listed in the file
1616
`doc-requirements.txt <https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt>`_
1717
as well as listed below:
1818

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

2728
.. note::
2829

@@ -39,10 +40,12 @@ All documentation is built from the :file:`doc/` directory. This directory conta
3940

4041
.. note::
4142

42-
An exception to this are the directories :file:`gallery` and :file:`tutorials`, which
43-
exist in the root directory. These contain Python files that are built by `Sphinx Gallery`_.
44-
When the docs are built, directories of the same name will be generated inside of :file:`docs/`.
45-
The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be 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.
4649

4750
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directories
4851
Sphinx parses, how the docs are built, and how the extensions are used.
@@ -52,30 +55,36 @@ Building the docs
5255

5356
The documentation sources are found in the :file:`doc/` directory in
5457
the trunk. To build the users guide in html format, cd into
55-
:file:`doc/` and do::
58+
:file:`doc/` and run
5659

57-
python make.py html
60+
.. code:: sh
5861
59-
or::
62+
make html
6063
61-
./make.py html
64+
Other useful invocations include
6265

63-
There are many other flags you can pass to ``make.py``, and you can see the
64-
full list inside that file. Here are two useful ones:
66+
.. code:: sh
6567
66-
* ``clean`` will delete the built Sphinx files. Use this command if you're getting strange
67-
errors about missing paths or broken links, particularly if you move files around.
68-
* ``latex`` builds a PDF of the documentation.
68+
# Delete built files. May help if you get errors about missing paths or
69+
# broken links.
70+
make clean
6971
70-
In addition, these are useful flags:
72+
# Build pdf docs.
73+
make latexpdf
7174
72-
* ``--help`` will (among other things) display the allowed commands for ``make.py``.
73-
* ``--allowsphinxwarnings`` will allow the docs to continue building even if Sphinx
74-
throws a warning. This is useful for debugging and spot-checking many warnings
75-
at once.
75+
You can build the documentation with several options:
7676

77+
* ``make O=-W html`` turns Sphinx warnings into errors. The continuous
78+
integration script uses this option.
79+
* ``make O=-j4 html`` (for example) runs a parallel build with 4 processes.
80+
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
81+
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
7782

78-
Organization of matplotlib's documentation
83+
Multiple options can be combined using e.g. ``make O='-W -j4 ...' html``. On
84+
Windows, the option needs to be set as the ``SPHINXOPTS`` environment
85+
variable, e.g. ``set SPHINXOPTS=-W -j4 & make html``.
86+
87+
Organization of Matplotlib's documentation
7988
==========================================
8089

8190
The actual ReStructured Text files are kept in :file:`doc/users`,

‎doc/devel/release_guide.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ temporarily comment out the include and toctree glob; re-instate these after a
5454
release. Finally, make sure that the docs build cleanly ::
5555

5656
pushd doc
57-
python make.py html latex -n 16
57+
make O=-n$(nproc) html latexpdf
5858
popd
5959

6060
After the docs are built, check that all of the links, internal and external, are still
@@ -214,7 +214,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is::
214214
git checkout v2.0.0-doc
215215
git clean -xfd
216216
cd doc
217-
python make.py html latex -n 16
217+
make O=-n$(nproc) html latexpdf
218218

219219
which will build both the html and pdf version of the documentation.
220220

‎doc/make.bat

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