Skip to content

updating developer docs #8544

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 8 commits into from
Apr 28, 2017
Merged

updating developer docs #8544

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
83129fa
updating developer docs
choldgraf Apr 27, 2017
0baccc7
addressing comments
choldgraf Apr 28, 2017
530c62d
Update documenting_mpl.rst
choldgraf Apr 28, 2017
23f4757
Update documenting_mpl.rst
choldgraf Apr 28, 2017
5efe61c
Update documenting_mpl.rst
choldgraf Apr 28, 2017
ff1b20e
Update documenting_mpl.rst
choldgraf Apr 28, 2017
c6866a0
Update documenting_mpl.rst
choldgraf Apr 28, 2017
d73ff15
fixing link
choldgraf Apr 28, 2017
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
63 changes: 51 additions & 12 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,14 @@ Developer's tips for documenting matplotlib
Getting started
===============

The documentation for matplotlib is generated from ReStructured Text using the
Sphinx_ documentation generation tool.
The requirements are as follows (https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt)
Installing dependencies
-----------------------

The documentation for matplotlib is generated from reStructuredText using the
Sphinx_ documentation generation tool. There are several extra requirements that
are needed to build the documentation. They are listed in the file
`doc-requirements.txt <https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt>`_
as well as listed below:

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

.. note::

* You'll need a minimal working LaTeX distribution for many examples to run.
* `Graphviz <http://www.graphviz.org/Download.php>`_ is not a python package, and needs
to be installed separately.

General structure
-----------------

All documentation is built from the :file:`doc/` directory. This directory contains both
``.rst`` files that contain pages in the documentation, directories that contain more
``.rst`` files, and configuration files for Sphinx_.

.. note::

An exception to this are the directories :file:`gallery` and :file:`tutorials`, which
exist in the root directory. These contain Python files that are built by `Sphinx Gallery`_.
When the docs are built, directories of the same name will be generated inside of :file:`docs/`.
The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.

The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directories
Sphinx parses, how the docs are built, and how the extensions are used.

Building the docs
-----------------

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

./make.py html

you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
arguments to build everything.
There are many other flags you can pass to ``make.py``, and you can see the
full list inside that file. Here are two useful ones:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or run ./make.py --help? (maybe?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put this in the flags section


* ``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.
* ``latex`` builds a PDF of the documentation.

In addition, these are useful flags:

The output produced by Sphinx can be configured by editing the :file:`conf.py`
file located in the :file:`doc/`.
* ``--help`` will (among other things) display the allowed commands for ``make.py``.
* ``--allowsphinxwarnings`` will allow the docs to continue building even if Sphinx
throws a warning. This is useful for debugging and spot-checking many warnings
at once.


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

.. _Sphinx: http://www.sphinx-doc.org
.. _documentation: http://www.sphinx-doc.org/contents.html
.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup

* Please limit the text width of docstrings to 70 characters.

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

.. TODO: Add section about uploading docs

.. _Sphinx: http://www.sphinx-doc.org
.. _documentation: http://www.sphinx-doc.org/contents.html
.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/