matplotlib
diff --git a/‎doc/devel/documenting_mpl.rst
Lines changed: 28 additions & 67 deletions b/‎doc/devel/documenting_mpl.rst
Lines changed: 28 additions & 67 deletions
@@ -59,7 +59,9 @@ Building the docs
 -----------------
 
 The documentation sources are found in the :file:`doc/` directory in the trunk.
-To build the documentation in html format, cd into :file:`doc/` and run:
+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. To build the documentation in html format, cd into :file:`doc/` and run:
 
 .. code-block:: sh
 
@@ -137,12 +139,12 @@ Documents can be linked with the `:doc:` directive::
 
 .. code-block:: rst
 
-  :doc:`/faq/installing_faq`
+   :doc:`/faq/installing_faq`
 
 will link to :doc:`/faq/installing_faq`.
 
 Sections can also be given reference names.  For instance from the
-:doc:`/faq/installing_faq`:
+:doc:`/faq/installing_faq` link:
 
 .. code-block:: rst
 
@@ -151,7 +153,7 @@ Sections can also be given reference names.  For instance from the
    How to completely remove Matplotlib
    ===================================
 
-   Occasionally, problems with Matplotlib can be solved with a clean
+   Occasionally, problems with Matplotlib can be solved with a clean...
 
 and refer to it using the standard reference syntax:
 
@@ -224,30 +226,33 @@ 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'
 
-.. _referring-to-mpl-docs:
+.. _rst-figures-and-includes
 
-Referring to data files
------------------------
+Including figures and files
+---------------------------
 
 In the documentation, you may want to include to a data file in the Matplotlib
 sources, e.g., a license file or an image file from :file:`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`, you can refer to the image icons with::
+file resides,
+
+Image files can directly included in pages with the ``image::`` directive.
+e.g., :file:`users/navigation_toolbar.rst` displays the toolbar icons
+with a call to a static image::
 
-    .. image:: ../../lib/matplotlib/mpl-data/images/subplots.png
+    .. image:: ../_static/toolbar.png
 
-In the :file:`users` subdirectory, if you want to refer to a file in the
-:file:`mpl-data` directory, you can use the symlink directory. For example,
-from :file:`customizing.rst`::
+as rendered on the page: :ref:`navigation-toolbar`.
 
-    .. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc
+Files can be included verbatim.  For instance the ``matplotlibrc`` file
+is important for customizing Matplotlib, and is included verbatim in the
+tutorial in :file:`/tutorials/introductory/customizing.py`::
 
-One exception to this is when referring to the examples directory. Relative
-paths are extremely confusing in the sphinx plot extensions, so it is easier
-to simply include a symlink to the files at the top doc level directory.
-This way, API documents like :meth:`matplotlib.pyplot.plot` can refer to the
-examples in a known location.
+    .. literalinclude:: ../../_static/matplotlibrc
+
+This is rendered as `/tutorials/introductory/customizing.py` (see the
+bottom of the page).  (Note that this is in a tutorial;  See
+:ref:`writing-examples-and-tutorials` below)
 
 In the top level :file:`doc` directory we have symlinks pointing to the
 Matplotlib :file:`examples`:
@@ -263,37 +268,9 @@ So we can include plots from the examples dir using the symlink:
 
     .. plot:: mpl_examples/pylab_examples/simple_plot.py
 
-
-`include` statements
---------------------
-
-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.
-It is also possible to include other documents through the use of an include
-statement, such as::
-
-  .. include:: ../../TODO
-
-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.
-
-.. _rest-adding-figures:
-
-Adding figures
---------------
-
-Figures in the example gallery can be referenced by te
-
-There are two options for where to put the code that generates a figure. If
-you want to include a plot in the examples gallery, the code should be added to
-the :file:`examples` directory. Plots from
-the :file:`examples` directory can then be referenced through the symlink
-``mpl_examples`` in the ``doc`` directory, e.g.:
-
-.. code-block:: rst
-
-  .. plot:: mpl_examples/lines_bars_and_markers/fill.py
+Note that the python script that generates the plot is referred to, rather
+than any plot that is created.  `Sphinx Gallery`_ will provide the incorrect
+reference when the documentation is built.
 
 
 .. _writing-docstrings:
@@ -390,6 +367,7 @@ to keep in mind:
              ['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.
@@ -406,23 +384,6 @@ to keep in mind:
      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)::
-
-  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