Skip to content

Commit e69bdaa

Browse files
phobsonphobson
authored
Merge pull request #8544 from choldgraf/devel_docs
DOC: update developer docs to better reflect their build deps
2 parents 81a7739 + d73ff15 commit e69bdaa

File tree

1 file changed

+51
-12
lines changed

1 file changed

+51
-12
lines changed

‎doc/devel/documenting_mpl.rst

Lines changed: 51 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,14 @@ Developer's tips for documenting matplotlib
77
Getting started
88
===============
99

10-
The documentation for matplotlib is generated from ReStructured Text using the
11-
Sphinx_ documentation generation tool.
12-
The requirements are as follows (https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt)
10+
Installing dependencies
11+
-----------------------
12+
13+
The documentation for matplotlib is generated from reStructuredText using the
14+
Sphinx_ documentation generation tool. There are several extra requirements that
15+
are needed to build the documentation. They are listed in the file
16+
`doc-requirements.txt <https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt>`_
17+
as well as listed below:
1318

1419
1. Sphinx-1.3 or later(Version 1.5.0 is not supported)
1520
2. numpydoc 0.4 or later
@@ -19,6 +24,31 @@ The requirements are as follows (https://github.com/matplotlib/matplotlib/blob/m
1924
6. pillow
2025
7. graphviz
2126

27+
.. note::
28+
29+
* 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+
to be installed separately.
32+
33+
General structure
34+
-----------------
35+
36+
All documentation is built from the :file:`doc/` directory. This directory contains both
37+
``.rst`` files that contain pages in the documentation, directories that contain more
38+
``.rst`` files, and configuration files for Sphinx_.
39+
40+
.. note::
41+
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.
46+
47+
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directories
48+
Sphinx parses, how the docs are built, and how the extensions are used.
49+
50+
Building the docs
51+
-----------------
2252

2353
The documentation sources are found in the :file:`doc/` directory in
2454
the trunk. To build the users guide in html format, cd into
@@ -30,11 +60,19 @@ or::
3060

3161
./make.py html
3262

33-
you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
34-
arguments to build everything.
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:
65+
66+
* ``clean`` will delete the built Sphinx files. Use this command if you're getting strange
67+
errors about missing paths or broken links, particularly if you move files around.
68+
* ``latex`` builds a PDF of the documentation.
69+
70+
In addition, these are useful flags:
3571

36-
The output produced by Sphinx can be configured by editing the :file:`conf.py`
37-
file located in the :file:`doc/`.
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.
3876

3977

4078
Organization of matplotlib's documentation
@@ -264,11 +302,6 @@ working with Sphinx in general. Here are a few additional things to keep in mind
264302
* The autodoc extension will handle index entries for the API, but additional
265303
entries in the index_ need to be explicitly added.
266304

267-
.. _Sphinx: http://www.sphinx-doc.org
268-
.. _documentation: http://www.sphinx-doc.org/contents.html
269-
.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html
270-
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
271-
272305
* Please limit the text width of docstrings to 70 characters.
273306

274307
* Keyword arguments should be described using a definition list.
@@ -504,3 +537,9 @@ Some helpful functions::
504537
Shift region to the right
505538

506539
.. TODO: Add section about uploading docs
540+
541+
.. _Sphinx: http://www.sphinx-doc.org
542+
.. _documentation: http://www.sphinx-doc.org/contents.html
543+
.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html
544+
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
545+
.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/

0 commit comments

Comments
 (0)