Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 7103985

Browse files
tacaswelltacaswell
committed
DOC : clean up MEP10, MEP11 headings
1 parent e67f8d1 commit 7103985

2 files changed

Lines changed: 29 additions & 27 deletions

File tree

‎doc/devel/MEP/MEP10.rst‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,25 @@
1-
MEP10: Docstring consistency
2-
============================
1+
==============================
2+
MEP10: Docstring consistency
3+
==============================
34
.. contents::
45
:local:
56

67
Status
7-
------
8+
======
89

910
**Progress**
1011

1112
Targeted for 1.3
1213

1314
Branches and Pull requests
14-
--------------------------
15+
==========================
1516

1617
#1665
1718
#1757
1819
#1795
1920

2021
Abstract
21-
--------
22+
========
2223

2324
matplotlib has a great deal of inconsistency between docstrings. This
2425
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`
3637
script rather than a Makefile.
3738

3839
Detailed description
39-
--------------------
40+
====================
4041

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

4647
Numpy docstring format
47-
''''''''''''''''''''''
48+
----------------------
4849

4950
`Numpy docstring format
5051
<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
5556
the Numpy/Scipy community.
5657

5758
Cross references
58-
''''''''''''''''
59+
----------------
5960

6061
Most of the docstrings in matplotlib use explicit "roles" when linking
6162
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```
6768
could be written as ```~axes.Axes.set_xlim```.
6869

6970
Overriding signatures
70-
'''''''''''''''''''''
71+
---------------------
7172

7273
Many methods in matplotlib use the ``*args`` and ``**kwargs`` syntax
7374
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
104105
generated documentation.
105106

106107
Linking rather than duplicating
107-
'''''''''''''''''''''''''''''''
108+
-------------------------------
108109

109110
Many of the docstrings include long lists of accepted keywords by
110111
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
117118
link to them, rather than including them verbatim.
118119

119120
autosummary extension
120-
'''''''''''''''''''''
121+
---------------------
121122

122123
The Sphinx autosummary extension should be used to generate summary
123124
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
126127
methods together.
127128

128129
Examples linking to relevant documentation
129-
''''''''''''''''''''''''''''''''''''''''''
130+
------------------------------------------
130131

131132
The examples, while helpful at illustrating how to use a feature, do
132133
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
136137
documentation.
137138

138139
Documentation using help() vs a browser
139-
''''''''''''''''''''''
140+
---------------------------------------
140141

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

146147
Implementation
147-
--------------
148+
==============
148149

149150
1. The numpydoc extensions should be turned on for matplotlib. There
150151
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
181182
independently, though 5 has some dependency on 3.
182183

183184
Backward compatibility
184-
----------------------
185+
======================
185186

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

189190
Alternatives
190-
------------
191+
============
191192

192193
None yet discussed.

‎doc/devel/MEP/MEP11.rst‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
MEP11: Third-party dependencies
2-
===============================
1+
=================================
2+
MEP11: Third-party dependencies
3+
=================================
34

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

1011
Status
11-
------
12+
======
1213

1314
**Completed** -- needs to be merged
1415

1516
Branches and Pull requests
16-
--------------------------
17+
==========================
1718

1819
#1157: Use automatic dependency resolution
1920

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

2425
Abstract
25-
--------
26+
========
2627

2728
One of the goals of matplotlib has been to keep it as easy to install
2829
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
4243
orthogonal set of problems.
4344

4445
Detailed description
45-
--------------------
46+
====================
4647

4748
matplotlib depends on the following third-party Python libraries:
4849

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

5859
Current behavior
59-
````````````````
60+
----------------
6061

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

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

101102

102103
Desired behavior
103-
````````````````
104+
----------------
104105

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

113114
Implementation
114-
--------------
115+
==============
115116

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

153154
Backward compatibility
154-
----------------------
155+
======================
155156

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

163164
Alternatives
164-
------------
165+
============
165166

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

0 commit comments

Comments
 (0)