Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Massive MEP move #4293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 23 commits into from
Mar 30, 2015
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
DOC : clean up MEP10, MEP11 headings
  • Loading branch information
tacaswell committed Mar 28, 2015
commit 71039859e6afc38d89d765a7dabe6481c7e7e63c
33 changes: 17 additions & 16 deletions 33 doc/devel/MEP/MEP10.rst
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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>`_:
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
23 changes: 12 additions & 11 deletions 23 doc/devel/MEP/MEP11.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
MEP11: Third-party dependencies
===============================
=================================
MEP11: Third-party dependencies
=================================

.. contents::
:local:
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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`:

Expand Down Expand Up @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.