Skip to content

WIP Update documentating guide #9804

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

Closed
wants to merge 1 commit into from
Closed

WIP Update documentating guide #9804

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
189 changes: 65 additions & 124 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _documenting-matplotlib:

===========================================
Developer's tips for documenting matplotlib
Developer's tips for documenting Matplotlib
===========================================

Getting started
Expand All @@ -10,36 +10,37 @@ Getting started
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
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)
1. Sphinx-1.3 or later (version 1.5.0 is not supported)
2. numpydoc 0.4 or later
3. IPython
4. Mock
5. colorspacious
6. pillow
7. graphviz
8. spinx-gallery 0.1.12 or later

.. 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
-----------------
General file 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
An exception to this are the directories :file:`examples` 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.
Expand All @@ -51,15 +52,11 @@ 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
:file:`doc/` and do::
the trunk. To build the documentation in html format, cd into
:file:`doc/` and run::

python make.py html

or::

./make.py html

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:

Expand All @@ -75,16 +72,16 @@ In addition, these are useful flags:
at once.


Organization of matplotlib's documentation
Organization of Matplotlib's documentation
==========================================

The actual ReStructured Text files are kept in :file:`doc/users`,
:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is
:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users
guide, developers guide, api reference, and faqs. The documentation suite is
guide, developers guide, api reference, and FAQs. The documentation suite is
built as a single document in order to make the most effective use of cross
referencing, we want to make navigating the Matplotlib documentation as easy as
possible.
referencing (we want to make navigating the Matplotlib documentation as easy as
possible).

Additional files can be added to the various guides by including their base
file name (the .rst extension is not necessary) in the table of contents.
Expand All @@ -97,9 +94,9 @@ docstrings
----------

In addition to the "narrative" documentation described above,
matplotlib also defines its API reference documentation in docstrings.
Matplotlib also defines its API reference documentation in docstrings.
For the most part, these are standard Python docstrings, but
matplotlib also includes some features to better support documenting
Matplotlib also includes some features to better support documenting
getters and setters.

Matplotlib uses artist introspection of docstrings to support
Expand All @@ -119,7 +116,7 @@ e.g., in :class:`matplotlib.lines.Line2D`::
ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
"""

Since matplotlib uses a lot of pass-through ``kwargs``, e.g., in every
Since Matplotlib uses a lot of pass-through keyword arguments (``kwargs``), e.g., in every
function that creates a line (:func:`~matplotlib.pyplot.plot`,
:func:`~matplotlib.pyplot.semilogx`,
:func:`~matplotlib.pyplot.semilogy`, etc...), it can be difficult for
Expand All @@ -131,11 +128,11 @@ function that takes a ``**kwargs``. The requirements are:
require multiple docstring edits.

2. as automated as possible so that as properties change, the docs
are updated automagically.
are updated automatically.

The function :func:`matplotlib.artist.kwdoc` and the decorator
:func:`matplotlib.docstring.dedent_interpd` facilitate this. They combine
python string interpolation in the docstring with the matplotlib
python string interpolation in the docstring with the Matplotlib
artist introspection facility that underlies ``setp`` and ``getp``.
The ``kwdoc`` function gives the list of properties as a docstring. In order
to use this in another docstring, first update the
Expand Down Expand Up @@ -181,135 +178,81 @@ Formatting
The Sphinx website contains plenty of documentation_ concerning ReST markup and
working with Sphinx in general. Here are a few additional things to keep in mind:

* Please familiarize yourself with the Sphinx directives for `inline
markup`_. Matplotlib's documentation makes heavy use of cross-referencing and
other semantic markup. For example, when referring to external files, use the
``:file:`` directive.
* Matplotlib's documentation makes heavy use of cross-referencing and
other semantic markup. Details can be found in Sphinx directives for `inline
markup`_. For example, when referring to external files, the
``:file:`` directive should be used.

* Function arguments and keywords should be referred to using the *emphasis*
role. This will keep matplotlib's documentation consistent with Python's
documentation::
* Please keep the :ref:`glossary` in mind when writing documentation. You can
create a references to a term in the glossary with the ``:term:`` role.

* The autodoc extension will handle index entries for the API, but additional
entries in the index_ need to be explicitly added.

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

Function arguments
------------------
Function arguments and keywords should be referred to using the *emphasis*
role. This will keep Matplotlib's documentation consistent with Python's
documentation::

Here is a description of *argument*

Please do not use the `default role`::
Please do not use the `default role`::

Please do not describe `argument` like this.

nor the ``literal`` role::
nor the ``literal`` role::

Please do not describe ``argument`` like this.

* Sphinx does not support tables with column- or row-spanning cells for
latex output. Such tables can not be used when documenting matplotlib.
latex output. Such tables can not be used when documenting Matplotlib.

* Mathematical expressions can be rendered as png images in html, and in the
usual way by latex. For example:
Maths
-----
Mathematical expressions can be rendered as png images in html, and in the
usual way by latex. For example:

``:math:`\sin(x_n^2)``` yields: :math:`\sin(x_n^2)`, and::

.. math::

\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}

yields:
yields:

.. math::

\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}

* Interactive IPython sessions can be illustrated in the documentation using
the following directive::
IPython code
------------
Interactive IPython sessions can be illustrated in the documentation using
the following directive::

.. sourcecode:: ipython

In [69]: lines = plot([1,2,3])

which would yield:
which would yield:

.. sourcecode:: ipython

In [69]: lines = plot([1,2,3])

* Footnotes [#]_ can be added using ``[#]_``, followed later by::
Footnotes
---------
Footnotes [#]_ can be added using ``[#]_``, followed later by::

.. rubric:: Footnotes

.. [#]

.. rubric:: Footnotes

Copy link
Member Author

Choose a reason for hiding this comment

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

I've been fairly ruthless deleting stuff here, as how to do all this properly is documented in the numpydoc guide (which I will add a link to in this document at some point)

.. [#] For example.

* Use the *note* and *warning* directives, sparingly, to draw attention to
important comments::

.. note::
Here is a note

yields:

.. note::
here is a note

also:

.. warning::
here is a warning

* Use the *deprecated* directive when appropriate::

.. deprecated:: 0.98
This feature is obsolete, use something else.

yields:

.. deprecated:: 0.98
This feature is obsolete, use something else.
.. rubric:: Footnotes

* Use the *versionadded* and *versionchanged* directives, which have similar
syntax to the *deprecated* role::

.. versionadded:: 0.98
The transforms have been completely revamped.

.. versionadded:: 0.98
The transforms have been completely revamped.

* Use the *seealso* directive, for example::

.. seealso::

Using ReST :ref:`emacs-helpers`:
One example

A bit about :ref:`referring-to-mpl-docs`:
One more

yields:

.. seealso::

Using ResT :ref:`emacs-helpers`:
One example

A bit about :ref:`referring-to-mpl-docs`:
One more

* Please keep the :ref:`glossary` in mind when writing documentation. You can
create a references to a term in the glossary with the ``:term:`` role.

* The autodoc extension will handle index entries for the API, but additional
entries in the index_ need to be explicitly added.

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

* Keyword arguments should be described using a definition list.

.. note::
matplotlib makes extensive use of keyword arguments as pass-through
arguments, there are a many cases where a table is used in place of a
definition list for autogenerated sections of docstrings.
.. [#] For example.

Figures
=======
Expand Down Expand Up @@ -354,12 +297,12 @@ insert the following special comment anywhere in the script::
Animations
----------

We have a matplotlib google/gmail account with username ``mplgithub``
We have a Matplotlib Google/gmail account with username ``mplgithub``
which we used to setup the github account but can be used for other
purposes, like hosting google docs or youtube videos. You can embed a
matplotlib animation in the docs by first saving the animation as a
Matplotlib animation in the docs by first saving the animation as a
movie using :meth:`matplotlib.animation.Animation.save`, and then
uploading to `matplotlib's youtube
uploading to `Matplotlib's youtube
channel <https://www.youtube.com/user/matplotlib>`_ and inserting the
embedding string youtube provides like::

Expand Down Expand Up @@ -388,15 +331,15 @@ Referring to mpl documents
==========================

In the documentation, you may want to include to a document in the
matplotlib src, e.g., a license file or an image file from `mpl-data`,
Matplotlib src, e.g., a license file or an image file from `mpl-data`,
refer to it via a relative path from the document where the rst file
resides, e.g., in :file:`users/navigation_toolbar.rst`, we refer to the
image icons with::

.. image:: ../../lib/matplotlib/mpl-data/images/subplots.png

In the `users` subdirectory, if I want to refer to a file in the mpl-data
directory, I use the symlink directory. For example, from
In the `users` subdirectory, if you want to refer to a file in the mpl-data
directory, you can use the symlink directory. For example, from
`customizing.rst`::

.. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc
Expand Down Expand Up @@ -437,8 +380,8 @@ and refer to it using the standard reference syntax::

See :ref:`howto-webapp`

Keep in mind that we may want to reorganize the contents later, so
let's avoid top level names in references like ``user`` or ``devel``
Keep in mind that we may want to re-organize the contents later, so
please try to avoid top level names in references like ``user`` or ``devel``
or ``faq`` unless necessary, because for example the FAQ "what is a
backend?" could later become part of the users guide, so the label::

Expand All @@ -448,11 +391,9 @@ is better than::

.. _faq-backend

In addition, since underscores are widely used by Sphinx itself, let's prefer
In addition, since underscores are widely used by Sphinx itself, please use
hyphens to separate words.



Section names, etc
==================

Expand All @@ -464,7 +405,7 @@ Inheritance diagrams
====================

Class inheritance diagrams can be generated with the
``inheritance-diagram`` directive. To use it, you provide the
``inheritance-diagram`` directive. To use it, provide the
directive with a number of class or module names (separated by
whitespace). If a module name is provided, all classes in that module
will be used. All of the ancestors of these classes will be included
Expand Down