Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit7046f57

Browse files
committed
Switch to makefile-based doc build.
1 parentbd38f40 commit7046f57

File tree

14 files changed

+121
-299
lines changed

14 files changed

+121
-299
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:pythonmake.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 = foo
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -Mhelp"$(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: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
1+
.. highlight:: sh
2+
13
Matplotlib documentation
24
========================
35

4-
56
Building the documentation
67
--------------------------
78

89
To build the documentation, you will need additional dependencies:
910

10-
* Sphinx-1.3 or later (version1.5.0 is not supported)
11-
*numpydoc 0.4 or later
11+
* Sphinx>=1.3, !=1.5.0, !=1.6.4
12+
*colorspacious
1213
* IPython
1314
* mock
14-
* colorspacious
15-
* pillow
15+
* numpydoc>=0.4
16+
* Pillow
17+
* sphinx-gallery>=0.1.12
1618
* graphviz
1719

1820
All of these dependencies *except graphviz* can be installed through pip::
@@ -21,25 +23,30 @@ All of these dependencies *except graphviz* can be installed through pip::
2123

2224
or all of them via conda and pip::
2325

24-
conda install sphinx numpydoc ipython mock graphviz pillow \
25-
sphinx-gallery
26+
conda install sphinx ipython mock numpydoc pillow sphinx-gallery graphviz
2627
pip install colorspacious
2728

28-
To build the HTML documentation, type ``pythonmake.py html`` in this
29-
directory. The topfile of the results will be ./build/html/index.html
29+
To build the HTML documentation, type ``make html`` in this directory. The top
30+
file of the results will be:file:`./build/html/index.html`.
3031

3132
**Note that Sphinx uses the installed version of the package to build the
3233
documentation**: Matplotlib must be installed *before* the docs can be
3334
generated.
3435

3536
You can build the documentation with several options:
3637

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.
38+
* ``make O=-W html`` turns Sphinx warnings into errors. The continuous
39+
integration script uses this option.
40+
* ``make O=-j4 html`` (for example) runs a parallel build with 4 processes.
41+
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
42+
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
43+
44+
Multiple options can be combined using e.g. ``make O='-W -j4 ...' html``. On
45+
Windows, the option needs to be set as the ``SPHINXOPTS`` environment
46+
variable, e.g. ``set SPHINXOPTS=-W -j4 & make html``.
4047

4148
Organization
42-
-------------
49+
------------
4350

4451
This is the top level build directory for the Matplotlib
4552
documentation. All of the documentation is written using sphinx, a
@@ -57,12 +64,12 @@ python documentation system built on top of ReST. This directory contains
5764
* mpl_toolkits - documentation of individual toolkits that ship with
5865
Matplotlib
5966

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

6469
* conf.py - the sphinx configuration
6570

71+
* Makefile and make.bat - entry points for building the docs
72+
6673
* _static - used by the sphinx build system
6774

6875
* _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-
<ahref="http://depsy.org/package/python/matplotlib">
8-
<imgsrc="{{ pathto('_static/depsy_badge.svg', 1) }}">
9-
</a>
10-
11-
<br/>
12-
137
Travis-CI:<ahref="https://travis-ci.org/matplotlib/matplotlib">
148
<imgsrc="https://travis-ci.org/matplotlib/matplotlib.svg?branch=master"/>
159
</a>

‎doc/devel/documenting_mpl.rst

Lines changed: 36 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,19 @@ 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

2930
* You'll need a minimal working LaTeX distribution for many examples to run.
30-
* `Graphviz<http://www.graphviz.org/Download.php>`_ is not a python package, and needs
31+
* `Graphviz<http://www.graphviz.org/Download.php>`_ is not a python package, and needs
3132
to be installed separately.
3233

3334
General structure
@@ -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/` anddo::
58+
:file:`doc/` andrun
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 builtSphinxfiles.Use this command if you're getting strange
67-
errors about missing paths orbroken 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-
pythonmake.py htmllatex -n 16
57+
make htmllatexpdf -n$(nproc)
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-
pythonmake.py htmllatex -n 16
217+
make htmllatexpdf -n$(nproc)
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+
@ECHOOFF
2+
3+
pushd%~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if"%SPHINXBUILD%"=="" (
8+
setSPHINXBUILD=python -msphinx
9+
)
10+
setSOURCEDIR=.
11+
setBUILDDIR=build
12+
setSPHINXPROJ=foo
13+
14+
if"%1"==""goto help
15+
16+
%SPHINXBUILD%>NUL2>NUL
17+
iferrorlevel9009 (
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 /b1
27+
)
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)
[8]ページ先頭
©2009-2025 Movatter.jp