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

Switch to makefile-based doc build.#9513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
tacaswell merged 2 commits intomatplotlib:masterfromanntzer:make-docs
Dec 3, 2017
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion.circleci/config.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -68,7 +68,7 @@ mpl-run: &mpl-install

doc-run: &doc-build
name: Build documentation
command:pythonmake.py html
command: make html
working_directory: doc

doc-bundle-run: &doc-bundle
Expand Down
3 changes: 0 additions & 3 deletions.gitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -66,9 +66,6 @@ doc/gallery
doc/tutorials
doc/modules
doc/pyplots/tex_demo.png
doc/users/installing.rst
doc/_static/depsy_badge.svg
doc/_static/matplotlibrc
lib/dateutil
examples/*/*.pdf
examples/*/*.png
Expand Down
5 changes: 0 additions & 5 deletionsINSTALL.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
.. The source of this document is INSTALL.rst. During the doc build process,
.. this file is copied over to doc/users/installing.rst.
.. Therefore, you must edit INSTALL.rst, *not* doc/users/installing.rst!

.. _pip: https://pypi.python.org/pypi/pip/

==========
Expand All@@ -13,7 +9,6 @@ Installing
If you wish to contribute to the project, it's recommended you
:ref:`install the latest development version<install_from_source>`.


.. contents::

Installing an official release
Expand Down
4 changes: 2 additions & 2 deletionsdoc-requirements.txt
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -6,10 +6,10 @@
# Install the documentation requirements with:
# pip install -r doc-requirements.txt
#
sphinx>=1.3,!=1.5.0
sphinx>=1.3,!=1.5.0,!=1.6.4
colorspacious
ipython
mock
numpydoc
numpydoc>=0.4
pillow
sphinx-gallery>=0.1.12
20 changes: 20 additions & 0 deletionsdoc/Makefile
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS = -W
SPHINXBUILD = python -msphinx
SPHINXPROJ = matplotlib
SOURCEDIR = .
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
40 changes: 4 additions & 36 deletionsdoc/README.txt
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,13 @@
Matplotlib documentation
========================


Building the documentation
--------------------------

To build the documentation, you will need additional dependencies:

* Sphinx-1.3 or later (version 1.5.0 is not supported)
* numpydoc 0.4 or later
* IPython
* mock
* colorspacious
* pillow
* graphviz

All of these dependencies *except graphviz* can be installed through pip::

pip install -r ../doc-requirements.txt

or all of them via conda and pip::

conda install sphinx numpydoc ipython mock graphviz pillow \
sphinx-gallery
pip install colorspacious

To build the HTML documentation, type ``python make.py html`` in this
directory. The top file of the results will be ./build/html/index.html

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

You can build the documentation with several options:

* `--small` saves figures in low resolution.
* `--allowsphinxwarnings`: Don't turn Sphinx warnings into errors.
* `-n N` enables parallel build of the documentation using N process.
See :file:`doc/devel/documenting_mpl.rst` for instructions to build the docs.

Organization
-------------
------------

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

* make.py - the build script to build the html or PDF docs

* index.rst - the top level include document for Matplotlib docs

* conf.py - the sphinx configuration

* Makefile and make.bat - entry points for building the docs

* _static - used by the sphinx build system

* _templates - used by the sphinx build system
Expand Down
1 change: 0 additions & 1 deletiondoc/_static/depsy_badge_default.svg
View file
Open in desktop

This file was deleted.

6 changes: 0 additions & 6 deletionsdoc/_templates/badgesidebar.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,12 +4,6 @@

<br/>

<a href="http://depsy.org/package/python/matplotlib">
<img src="{{ pathto('_static/depsy_badge.svg', 1) }}">
</a>

<br/>

Travis-CI: <a href="https://travis-ci.org/matplotlib/matplotlib">
<img src="https://travis-ci.org/matplotlib/matplotlib.svg?branch=master"/>
</a>
Expand Down
56 changes: 37 additions & 19 deletionsdoc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -15,13 +15,14 @@ the Sphinx_ documentation generation tool. There are several extra requirements
that are needed to build the documentation. They are listed in
:file:`doc-requirements.txt` and listed below:

1. Sphinx 1.3 or later (1.5.0 is not supported)
2. numpydoc 0.4 or later
3. IPython
4. mock
5. colorspacious
6. Pillow
7. Graphviz
* Sphinx>=1.3, !=1.5.0, !=1.6.4
* colorspacious
* IPython
* mock
* numpydoc>=0.4
* Pillow
* sphinx-gallery>=0.1.12
* graphviz

.. note::

Expand DownExpand Up@@ -69,24 +70,41 @@ Building the docs
-----------------

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

.. code-block:: sh

pythonmake.py html
make html

The list of commands and flags for ``make.py`` can be listed by running
``python make.py --help``. In particular,
Other useful invocations include

* ``python make.py clean`` will delete the built Sphinx files. Use this command
if you're getting strange errors about missing paths or broken links,
particularly if you move files around.
* ``python make.py latex`` builds a PDF of the documentation.
* The ``--allowsphinxwarnings`` flag allows the docs to continue building even
if Sphinx throws a warning. This is useful for debugging and spot-checking
many warnings at once.
.. code-block:: sh

# Delete built files. May help if you get errors about missing paths or
# broken links.
make clean

# Build pdf docs.
make latexpdf

The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
errors. To unset it, use

.. code-block:: sh

make SPHINXOPTS= html

You can use the ``O`` variable to set additional options:

* ``make O=-j4 html`` runs a parallel build with 4 processes.
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.

Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
html``.

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

Writing new documentation
=========================
Expand Down
6 changes: 2 additions & 4 deletionsdoc/devel/release_guide.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -53,9 +53,7 @@ by merging all files in :file:`doc/users/next_whats_new/` coherently. Also,
temporarily comment out the include and toctree glob; re-instate these after a
release. Finally, make sure that the docs build cleanly ::

pushd doc
python make.py html latex -n 16
popd
make -Cdoc O=-n$(nproc) html latexpdf

After the docs are built, check that all of the links, internal and external, are still
valid. We use ``linkchecker`` for this, which has not been ported to python3 yet. You will
Expand DownExpand Up@@ -214,7 +212,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is::
git checkout v2.0.0-doc
git clean -xfd
cd doc
pythonmake.py html latex -n 16
make O=-n$(nproc) html latexpdf

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

Expand Down
38 changes: 38 additions & 0 deletionsdoc/make.bat
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=python -msphinx
)
set SOURCEDIR=.
set BUILDDIR=build
set SPHINXPROJ=matplotlib
set SPHINXOPTS=-W
set O=

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
echo.then set the SPHINXBUILD environment variable to point to the full
echo.path of the 'sphinx-build' executable. Alternatively you may add the
echo.Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
Loading
[8]ページ先頭
©2009-2025 Movatter.jp