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

Commit7e8ccbc

Browse files
committed
Switch to makefile-based doc build.
1 parent0e3dd2d commit7e8ccbc

File tree

14 files changed

+102
-319
lines changed

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: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: 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/` 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 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-
pythonmake.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+
@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