DOC : clean up MEP10, MEP11 headings

matplotlib · efiring · Mar 30, 2015 · Mar 28, 2015 · Mar 28, 2015 · Mar 28, 2015
commit 71039859e6afc38d89d765a7dabe6481c7e7e63c
diff --git a/doc/devel/MEP/MEP10.rst b/doc/devel/MEP/MEP10.rst
@@ -1,24 +1,25 @@
-MEP10: Docstring consistency
-============================
+==============================
+ MEP10: Docstring consistency
+==============================
 .. contents::
   :local:

 Status
------
+======

 **Progress**

 Targeted for 1.3

 Branches and Pull requests
--------------------------
+==========================

 #1665
 #1757
 #1795

 Abstract
--------
+========

 matplotlib has a great deal of inconsistency between docstrings.  This
 not only makes the docs harder to read, but it is harder on
@@ -36,15 +37,15 @@ Building the documentation takes a long time and uses a `make.py`
 script rather than a Makefile.

 Detailed description
--------------------
+====================

 There are number of new tools and conventions available since
 matplotlib started using Sphinx that make life easier.  The following
 is a list of proposed changes to docstrings, most of which involve
 these new features.

 Numpy docstring format
-''''''''''''''''''''''
+----------------------

 `Numpy docstring format
 <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_:
@@ -55,7 +56,7 @@ own, but this is a strong choice, as it's well used and understood in
 the Numpy/Scipy community.

 Cross references
-''''''''''''''''
+----------------

 Most of the docstrings in matplotlib use explicit "roles" when linking
 to other items, for example: ``:func:`myfunction```.  As of Sphinx
@@ -67,7 +68,7 @@ a current module, so links like ```~matplotlib.axes.Axes.set_xlim```
 could be written as ```~axes.Axes.set_xlim```.

 Overriding signatures
-'''''''''''''''''''''
+---------------------

 Many methods in matplotlib use the ``*args`` and ``**kwargs`` syntax
 to dynamically handle the keyword arguments that are accepted by the
@@ -104,7 +105,7 @@ The explicit signature will replace the actual Python one in the
 generated documentation.

 Linking rather than duplicating
-'''''''''''''''''''''''''''''''
+-------------------------------

 Many of the docstrings include long lists of accepted keywords by
 interpolating things into the docstring at load time.  This makes the
@@ -117,7 +118,7 @@ purpose is for help.  The docstrings that refer to these tables should
 link to them, rather than including them verbatim.

 autosummary extension
-'''''''''''''''''''''
+---------------------

 The Sphinx autosummary extension should be used to generate summary
 tables, that link to separate pages of documentation.  Some classes
@@ -126,7 +127,7 @@ one method per page, whereas smaller classes should have all of their
 methods together.

 Examples linking to relevant documentation
-''''''''''''''''''''''''''''''''''''''''''
+------------------------------------------

 The examples, while helpful at illustrating how to use a feature, do
 not link back to the relevant docstrings.  This could be addressed by
@@ -136,15 +137,15 @@ docstrings could easily include references to any other part of the
 documentation.

 Documentation using help() vs a browser
-''''''''''''''''''''''
+---------------------------------------

 Using Sphinx markup in the source allows for good-looking docs in your
 browser, but the markup also makes the raw text returned using help()
 look terrible. One of the aims of improving the docstrings should be
 to make both methods of accessing the docs look good.

 Implementation
--------------
+==============

 1. The numpydoc extensions should be turned on for matplotlib.  There
   is an important question as to whether these should be included in
@@ -181,12 +182,12 @@ Steps 1, 2, and 3 are interdependent.  4 and 5 may be done
 independently, though 5 has some dependency on 3.

 Backward compatibility
----------------------
+======================

 As this mainly involves docstrings, there should be minimal impact on
 backward compatibility.

 Alternatives
------------
+============

 None yet discussed.
diff --git a/doc/devel/MEP/MEP11.rst b/doc/devel/MEP/MEP11.rst
@@ -1,5 +1,6 @@
-MEP11: Third-party dependencies
-===============================
+=================================
+ MEP11: Third-party dependencies
+=================================

 .. contents::
   :local:
@@ -8,12 +9,12 @@ This MEP attempts to improve the way in which third-party dependencies
 in matplotlib are handled.

 Status
------
+======

 **Completed** -- needs to be merged

 Branches and Pull requests
--------------------------
+==========================

 #1157: Use automatic dependency resolution

@@ -22,7 +23,7 @@ Branches and Pull requests
 #1261: Update six to 1.2

 Abstract
--------
+========

 One of the goals of matplotlib has been to keep it as easy to install
 as possible.  To that end, some third-party dependencies are included
@@ -42,7 +43,7 @@ confuse the issue.  C libraries represent a larger and mostly
 orthogonal set of problems.

 Detailed description
--------------------
+====================

 matplotlib depends on the following third-party Python libraries:

@@ -56,7 +57,7 @@ matplotlib depends on the following third-party Python libraries:
     optional, but one is required for an interactive GUI)

 Current behavior
-````````````````
+----------------

 When installing from source, a `git` checkout or `pip`:

@@ -100,7 +101,7 @@ inclusion because of this burden.


 Desired behavior
-````````````````
+----------------

 Third-party dependencies are downloaded and installed from their
 canonical locations by leveraging `pip`, `distribute` and `PyPI`.
@@ -111,7 +112,7 @@ aren't installed.  This will allow the user to decide whether they
 want to bother installing a particular feature.

 Implementation
--------------
+==============

 For installing from source, and assuming the user has all of the
 C-level compilers and dependencies, this can be accomplished fairly
@@ -151,7 +152,7 @@ installed using an installer.
 TODO: How does this relate to the Mac OS-X installer?

 Backward compatibility
----------------------
+======================

 At present, matplotlib can be installed from source on a machine
 without the third party dependencies and without an internet
@@ -161,7 +162,7 @@ PyPI) will be required to install matplotlib for the first time.
 accessing the network).

 Alternatives
------------
+============

 Distributing binary `eggs` doesn't feel like a usable solution.  That
 requires getting `easy_install` installed first, and Windows users