DOC: Minor enhancements to documenting_mpl

jklymak · jklymak · commit d4f97efce6ed · 2017-11-28T12:42:43.000-08:00
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.
@@ -96,7 +97,8 @@ 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 +138,8 @@ An example docstring looks like:
         axhline: horizontal line across the axes
         """
 
+See the `~.Axes.hlines` for how this renders.
+
 The Sphinx website also contains plenty of documentation_ concerning ReST
 markup and working with Sphinx in general.
 
@@ -148,10 +152,16 @@ the name to refer to in back ticks, for example:
 
   `~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)::
+We can also link to other packages via ``intersphinx``:
+
+.. code-block:: Python
+
+  `numpy.mean`
+
+will return this link: `numpy.mean`.  This works for Python, Numpy, Scipy,
+and 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)::
 
   python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv'
 
@@ -181,12 +191,15 @@ nor the ````literal```` role:
 
 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
 
@@ -198,8 +211,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
