Skip to content

DOCS: optional doc building dependencies #18610

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 30, 2020
Merged

DOCS: optional doc building dependencies #18610

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
23 changes: 16 additions & 7 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Installing dependencies
The documentation for Matplotlib is generated from reStructuredText (ReST_)
using the Sphinx_ documentation generation tool. To build the documentation
you will need to (1) set up an appropriate Python environment and (2)
separately install LaTeX and Graphviz.
separately install our external dependencies.

To (1) set up an appropriate Python environment for building the
documentation, you should:
Expand All @@ -70,16 +70,25 @@ shown below:
.. include:: ../../requirements/doc/doc-requirements.txt
:literal:

To (2) set up LaTeX and Graphviz dependencies you should:
For (2), the Matplotlib docs require that you:

* install a minimal working LaTeX distribution
* install the LaTeX packages cm-super and dvipng
* install `Graphviz <http://www.graphviz.org/download>`_
* install the LaTeX packages cm-super and dvipng. If your OS bundles ``TexLive``,
then often the "complete" version of the installer will automatically include
these packages (e.g. "texlive-full" or "texlive-all").
* (suggested) install `Inkscape <https://inkscape.org>`_.
* (suggested) install `optipng <http://optipng.sourceforge.net>`_.
* (suggested) install the "Humor Sans" font (aka the "XKCD" font), or the free
alternative `Comic Neue <http://comicneue.com/>`_.

.. note::

The documentation will not build without LaTeX and Graphviz. These are not
Python packages and must be installed separately.
Python packages and must be installed separately. The documentation can be
built without Inkscape and optipng, but the build process will raise various
warnings. If the build process warns that you are missing fonts, make sure
your LaTeX distribution bundles cm-super or install it separately.

Building the docs
-----------------
Expand Down Expand Up @@ -111,7 +120,7 @@ it, use
.. code-block:: sh

make SPHINXOPTS= html

On Windows the arguments must be at the end of the statement:

.. code-block:: bat
Expand All @@ -131,8 +140,8 @@ On Windows, either use the format shown above or set options as environment vari

.. code-block:: bat

set O=-W --keep-going -j4
make html
set O=-W --keep-going -j4
make html

.. _writing-rest-pages:

Expand Down