matplotlib · jklymak · Nov 28, 2017 · anntzer · Nov 28, 2017 · jklymak
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -43,16 +43,17 @@ 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.
 
-.. note::
-
-   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,
-   the directories :file:`docs/gallery` and :file:`docs/tutorials`
-   are automatically generated. Do not edit the rst files in :file:docs/gallery
-   and :file:docs/tutorials, as they are rebuilt from the original sources in
-   the root directory.
-
+Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
+the docstrings of the classes in the Matplotlib library.  Except for
+:file:`doc/api/api_changes/`, these ``.rst`` are created when the
+documentation is built.
+
+Similarly, the contents of :file:`docs/gallery` and :file:`docs/tutorials` are
+generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
+:file:`tutorials`.  These sources consist of python scripts that have ReST
+documentation built into their comments.  Again, don't directly edit the
+``.rst`` files in :file:`docs/gallery` and :file:`docs/tutorials` as they are
+regenerated when the documentation are built.
 
 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.
@@ -91,12 +92,19 @@ The list of commands and flags for ``make.py`` can be listed by running
 Writing new documentation
 =========================
 
+As noted above, most documentation is either in the docstring of individual
+classes and methods, in explicit ``.rst`` files, or in examples and tutorials.
+
+Writing self-documenting docstrings
+-----------------------------------
+
 Most documentation lives in "docstrings". These are comment blocks in source
 code that explain how the code works. All new or edited docstrings should
 conform to the numpydoc guidelines. These split the docstring into a number
 of sections - see
 https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more
-details and a guide to how docstrings should be formatted.
+details and a guide to how docstrings should be formatted.  These docstrings
+eventually populate the :file:`doc/api` directory.
 
 An example docstring looks like:
 
@@ -136,6 +144,8 @@ An example docstring looks like:
         axhline: horizontal line across the axes
         """
 
+See the `~.Axes.hlines` documentation for how this renders.
+
 The Sphinx website also contains plenty of documentation_ concerning ReST
 markup and working with Sphinx in general.
 
@@ -147,7 +157,7 @@ markup and working with Sphinx in general.
    the current style are very welcome.
 
 Additional formatting conventions
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are some additional conventions, not handled by numpydoc and the Sphinx
 guide:
@@ -170,6 +180,7 @@ guide:
              ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
      'polar' | 'rectilinear'], optional
              The projection type of the axes.
+         """
 
   Alternatively, you can describe the valid parameter values in a dedicated
   section of the docstring.
@@ -186,26 +197,51 @@ guide:
      lines : `~matplotlib.collections.LineCollection`
 
 
-
 Linking to other code
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 To link to other methods, classes, or modules in Matplotlib you can encase
 the name to refer to in back ticks, for example:
 
 .. code-block:: python
 
   `~matplotlib.collections.LineCollection`
 
-It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.
-Sometimes it is tricky to get external Sphinx linking to work; to check that
-a something exists to link to the following shell command outputs a list of all
-objects that can be referenced (in this case for Numpy)::
+returns a link to the documentation of
+`~matplotlib.collections.LineCollection`.  If we want the full path of the
+class to be shown then we omit the tilde:
+
+.. code-block:: python
+
+  `matplotlib.collections.LineCollection`
+
+to get `matplotlib.collections.LineCollection`.  Its often not
+necessary to fully specify the class hierarchy unless there is a namespace
+collision between two packages:
+
+.. code-block:: python
+
+  `~.LineCollection`
+
+links just as well: `~.LineCollection`.
+
+Other packages can also be linked via ``intersphinx``:
+
+.. code-block:: Python
+
+  `numpy.mean`
+
+will return this link: `numpy.mean`.  This works for Python, Numpy, Scipy,
+and Pandas (full list is in :file:`doc/conf.py`). Sometimes it is tricky
+to get external Sphinx linking to work; to
+check that a something exists to link to the following shell command outputs
+a list of all objects that can be referenced (in this case for Numpy)::
 
   python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv'
 
 
 Function arguments
-------------------
+~~~~~~~~~~~~~~~~~~
+
 Function arguments and keywords within docstrings should be referred to using
 the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
 with Python's documentation:
@@ -214,27 +250,31 @@ with Python's documentation:
 
   Here is a description of *argument*
 
-Please do not use the ```default role```:
-
+Do not use the ```default role```:
 
 .. code-block:: rst
 
-   Please do not describe `argument` like this.
+   Do not describe `argument` like this.  As per the previous section,
+   this syntax will (unsuccessfully) attempt to resolve the argument as a
+   link to an object in the library.
 
 nor the ````literal```` role:
 
 .. code-block:: rst
 
-   Please do not describe ``argument`` like this.
+   Do not describe ``argument`` like this.
 
 Setters and getters
--------------------
-Matplotlib uses artist introspection of docstrings to support properties.
-All properties that you want to support through `~.pyplot.setp` and
-`~.pyplot.getp` should have a ``set_property`` and ``get_property`` method in
-the `~.matplotlib.artist.Artist` class. The setter methods use the docstring
-with the ACCEPTS token to indicate the type of argument the method accepts.
-e.g., in `.Line2D`:
+~~~~~~~~~~~~~~~~~~~
+
+Artist properties are implemented using setter and getter methods (because
+Matplotlib predates the introductions of the `property` decorator in Python).
+By convention, these setters and getters are named ``set_PROPERTYNAME`` and
+``get_PROPERTYNAME``; the list of properties thusly defined on an artist and
+their values can be listed by the `~.pyplot.setp` and `~.pyplot.getp` functions.
+
+Property setter methods should indicate the values they accept using a (legacy)
+special block in the docstring, starting with ``ACCEPTS``, as follows:
 
 .. code-block:: python
 
@@ -246,8 +286,21 @@ e.g., in `.Line2D`:
        ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
        """
 
+The ACCEPTS block is used to render a table of all properties and their
+acceptable values in the docs; it can also be displayed using, e.g.,
+``plt.setp(Line2D)`` (all properties) or ``plt.setp(Line2D, 'linestyle')``
+(just one property).
+
 Keyword arguments
------------------
+~~~~~~~~~~~~~~~~~
+
+.. note::
+
+  The information in this section is being actively discussed by the
+  development team, so use the docstring interpolation only if necessary.
+  This section has been left in place for now because this interpolation
+  is part of the existing documentation.
+
 Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function
 that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`,
 etc...), it can be difficult for the new user to know which ``kwargs`` are