Improve plot_directive's docstring and use it from the main docs.

f13c3dfac5221ffbfd31776ee391c9994fa2e68d
commit f13c3dfac5221ffbfd31776ee391c9994fa2e68d
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -213,19 +213,6 @@ Figures can be automatically generated from scripts and included in
 the docs.  It is not necessary to explicitly save the figure in the
 script, this will be done automatically at build time to ensure that
 the code that is included runs and produces the advertised figure.
-Several figures will be saved with the same basename as the filename
-when the documentation is generated (low and high res PNGs, a PDF).
-Matplotlib includes a Sphinx extension
-(:file:`sphinxext/plot_directive.py`) for generating the images from
-the python script and including either a png copy for html or a pdf
-for latex::
-
-   .. plot:: pyplots/pyplot_simple.py
-      :include-source:
-
-If the script produces multiple figures (through multiple calls to
-:func:`pyplot.figure`), each will be given a numbered file name and
-included.
 
 The path should be relative to the ``doc`` directory.  Any plots
 specific to the documentation should be added to the ``doc/pyplots``
@@ -238,8 +225,12 @@ directory.  e.g.::
 The ``:scale:`` directive rescales the image to some percentage of the
 original size, though we don't recommend using this in most cases
 since it is probably better to choose the correct figure size and dpi
-in mpl and let it handle the scaling. ``:include-source:`` will
-present the contents of the file, marked up as source code.
+in mpl and let it handle the scaling.
+
+Plot directive documentation
+''''''''''''''''''''''''''''
+
+.. automodule:: matplotlib.sphinxext.plot_directive
 
 Static figures
 --------------

diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -1,9 +1,9 @@
 """
-A special directive for including a matplotlib plot in a Sphinx
-document.
+A directive for including a matplotlib plot in a Sphinx document.
 
-In HTML output, `plot` will include a .png file with a link to a
-high-res .png and .pdf.  In LaTeX output, it will include a .pdf.
+By default, in HTML output, `plot` will include a .png file with a
+link to a high-res .png and .pdf.  In LaTeX output, it will include a
+.pdf.
 
 The source code for the plot may be included in one of three ways:
 
@@ -23,35 +23,33 @@
 
        .. plot:: path/to/plot.py plot_function1
 
-  2. Included as inline content to the directive::
+  2. Included as **inline content** to the directive::
 
-     .. plot::
+       .. plot::
+          import matplotlib.pyplot as plt
+          import matplotlib.image as mpimg
+          import numpy as np
+          img = mpimg.imread('_static/stinkbug.png')
+          imgplot = plt.imshow(img)
 
-        import matplotlib.pyplot as plt
-        import matplotlib.image as mpimg
-        import numpy as np
-        img = mpimg.imread('_static/stinkbug.png')
-        imgplot = plt.imshow(img)
+  3. Using **doctest** syntax::
 
-  3. Using doctest syntax::
-
-     .. plot::
-
-        A plotting example:
-
-        >>> import matplotlib.pyplot as plt
-        >>> plt.plot([1,2,3], [4,5,6])
+       .. plot:: foo
+          A plotting example:
+          >>> import matplotlib.pyplot as plt
+          >>> plt.plot([1,2,3], [4,5,6])
 
 Options
 -------
 
-The ``plot`` directive supports the options:
+The ``plot`` directive supports the following options:
 
     format : {'python', 'doctest'}
         Specify the format of the input
 
     include-source : bool
-        Whether to display the source code. Default can be changed in conf.py
+        Whether to display the source code. The default can be changed
+        using the `plot_include_source` variable in conf.py
 
     encoding : str
         If this source file is in a non-UTF8 or non-ASCII encoding,
@@ -61,7 +59,7 @@
 
     context : bool
         If provided, the code will be run in the context of all
-        previous plot directives for which the context option was
+        previous plot directives for which the `:context:` option was
         specified.  This only applies to inline code plot directives,
         not those run from files.