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

Commiteaf3f9e

Browse files
committed
Switch to makefile-based doc build.
1 parent4ed9996 commiteaf3f9e

File tree

14 files changed

+103
-315
lines changed

14 files changed

+103
-315
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 = matplotlib
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: 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-
<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 & 24 deletions
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/` anddo:
59+
:file:`doc/` andrun
5960

6061
..code-block::sh
6162
62-
pythonmake.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

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-
pythonmake.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: 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=matplotlib
13+
14+
%SPHINXBUILD%>NUL2>NUL
15+
iferrorlevel9009 (
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 /b1
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)
[8]ページ先頭
©2009-2025 Movatter.jp