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

Commit 8ec5b2c

Browse filesBrowse files
mdboommdboom
committed
Reorganize the developer docs. Most importantly, this adds a pull request checklist.
1 parent 12d0124 commit 8ec5b2c
Copy full SHA for 8ec5b2c

File tree

Expand file treeCollapse file tree

8 files changed

+485
-719
lines changed
Filter options
Expand file treeCollapse file tree

8 files changed

+485
-719
lines changed

‎doc/devel/coding_guide.rst

Copy file name to clipboardExpand all lines: doc/devel/coding_guide.rst
+84-483Lines changed: 84 additions & 483 deletions
Large diffs are not rendered by default.

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+78-6Lines changed: 78 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,84 @@ statement, such as::
4646

4747
.. include:: ../../TODO
4848

49+
docstrings
50+
----------
51+
52+
In addition to the "narrative" documentation described above,
53+
matplotlib also defines its API reference documentation in docstrings.
54+
For the most part, these are standard Python docstrings, but
55+
matplotlib also includes some features to better support documenting
56+
getters and setters.
57+
58+
Matplotlib uses artist introspection of docstrings to support
59+
properties. All properties that you want to support through ``setp``
60+
and ``getp`` should have a ``set_property`` and ``get_property``
61+
method in the :class:`~matplotlib.artist.Artist` class. Yes, this is
62+
not ideal given python properties or enthought traits, but it is a
63+
historical legacy for now. The setter methods use the docstring with
64+
the ACCEPTS token to indicate the type of argument the method accepts.
65+
Eg. in :class:`matplotlib.lines.Line2D`::
66+
67+
# in lines.py
68+
def set_linestyle(self, linestyle):
69+
"""
70+
Set the linestyle of the line
71+
72+
ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
73+
"""
74+
75+
Since matplotlib uses a lot of pass-through ``kwargs``, eg. in every
76+
function that creates a line (:func:`~matplotlib.pyplot.plot`,
77+
:func:`~matplotlib.pyplot.semilogx`,
78+
:func:`~matplotlib.pyplot.semilogy`, etc...), it can be difficult for
79+
the new user to know which ``kwargs`` are supported. Matplotlib uses
80+
a docstring interpolation scheme to support documentation of every
81+
function that takes a ``**kwargs``. The requirements are:
82+
83+
1. single point of configuration so changes to the properties don't
84+
require multiple docstring edits.
85+
86+
2. as automated as possible so that as properties change, the docs
87+
are updated automagically.
88+
89+
The functions :attr:`matplotlib.artist.kwdocd` and
90+
:func:`matplotlib.artist.kwdoc` to facilitate this. They combine
91+
python string interpolation in the docstring with the matplotlib
92+
artist introspection facility that underlies ``setp`` and ``getp``.
93+
The ``kwdocd`` is a single dictionary that maps class name to a
94+
docstring of ``kwargs``. Here is an example from
95+
:mod:`matplotlib.lines`::
96+
97+
# in lines.py
98+
artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
99+
100+
Then in any function accepting :class:`~matplotlib.lines.Line2D`
101+
pass-through ``kwargs``, eg. :meth:`matplotlib.axes.Axes.plot`::
102+
103+
# in axes.py
104+
def plot(self, *args, **kwargs):
105+
"""
106+
Some stuff omitted
107+
108+
The kwargs are Line2D properties:
109+
%(Line2D)s
110+
111+
kwargs scalex and scaley, if defined, are passed on
112+
to autoscale_view to determine whether the x and y axes are
113+
autoscaled; default True. See Axes.autoscale_view for more
114+
information
115+
"""
116+
pass
117+
plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd
118+
119+
Note there is a problem for :class:`~matplotlib.artist.Artist`
120+
``__init__`` methods, eg. :meth:`matplotlib.patches.Patch.__init__`,
121+
which supports ``Patch`` ``kwargs``, since the artist inspector cannot
122+
work until the class is fully defined and we can't modify the
123+
``Patch.__init__.__doc__`` docstring outside the class definition.
124+
There are some some manual hacks in this case, violating the
125+
"single entry point" requirement above -- see the
126+
``artist.kwdocd['Patch']`` setting in :mod:`matplotlib.patches`.
49127

50128
.. _formatting-mpl-docs:
51129

@@ -181,11 +259,6 @@ working with Sphinx in general. Here are a few additional things to keep in mind
181259
.. _`inline markup`: http://sphinx.pocoo.org/markup/inline.html
182260
.. _index: http://sphinx.pocoo.org/markup/para.html#index-generating-markup
183261

184-
Docstrings
185-
----------
186-
187-
In addition to the aforementioned formatting suggestions:
188-
189262
* Please limit the text width of docstrings to 70 characters.
190263

191264
* Keyword arguments should be described using a definition list.
@@ -195,7 +268,6 @@ In addition to the aforementioned formatting suggestions:
195268
arguments, there are a many cases where a table is used in place of a
196269
definition list for autogenerated sections of docstrings.
197270

198-
199271
Figures
200272
=======
201273

‎doc/devel/gitwash/development_workflow.rst

Copy file name to clipboardExpand all lines: doc/devel/gitwash/development_workflow.rst
+3Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,9 @@ without interfering with the output from the comparison. More detail?
134134
Note the three dots in the URL above (``master...my-new-feature``) and
135135
see :ref:`dot2-dot3`.
136136

137+
It's a good idea to consult the :ref:`pull-request-checklist` to make
138+
sure your pull request is ready for merging.
139+
137140
Asking for your changes to be merged into the main repo
138141
=======================================================
139142

‎doc/devel/index.rst

Copy file name to clipboardExpand all lines: doc/devel/index.rst
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,10 @@
1313
:maxdepth: 2
1414

1515
coding_guide.rst
16+
license.rst
1617
gitwash/index.rst
18+
testing.rst
1719
documenting_mpl.rst
1820
release_guide.rst
1921
transformations.rst
2022
add_new_projection.rst
21-
outline.rst

‎doc/devel/license.rst

Copy file name to clipboard
+69Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. _license-discussion:
2+
3+
Licenses
4+
========
5+
6+
Matplotlib only uses BSD compatible code. If you bring in code from
7+
another project make sure it has a PSF, BSD, MIT or compatible license
8+
(see the Open Source Initiative `licenses page
9+
<http://www.opensource.org/licenses>`_ for details on individual
10+
licenses). If it doesn't, you may consider contacting the author and
11+
asking them to relicense it. GPL and LGPL code are not acceptable in
12+
the main code base, though we are considering an alternative way of
13+
distributing L/GPL code through an separate channel, possibly a
14+
toolkit. If you include code, make sure you include a copy of that
15+
code's license in the license directory if the code's license requires
16+
you to distribute the license with it. Non-BSD compatible licenses
17+
are acceptable in matplotlib toolkits (eg basemap), but make sure you
18+
clearly state the licenses you are using.
19+
20+
Why BSD compatible?
21+
-------------------
22+
23+
The two dominant license variants in the wild are GPL-style and
24+
BSD-style. There are countless other licenses that place specific
25+
restrictions on code reuse, but there is an important difference to be
26+
considered in the GPL and BSD variants. The best known and perhaps
27+
most widely used license is the GPL, which in addition to granting you
28+
full rights to the source code including redistribution, carries with
29+
it an extra obligation. If you use GPL code in your own code, or link
30+
with it, your product must be released under a GPL compatible
31+
license. I.e., you are required to give the source code to other
32+
people and give them the right to redistribute it as well. Many of the
33+
most famous and widely used open source projects are released under
34+
the GPL, including linux, gcc, emacs and sage.
35+
36+
The second major class are the BSD-style licenses (which includes MIT
37+
and the python PSF license). These basically allow you to do whatever
38+
you want with the code: ignore it, include it in your own open source
39+
project, include it in your proprietary product, sell it,
40+
whatever. python itself is released under a BSD compatible license, in
41+
the sense that, quoting from the PSF license page::
42+
43+
There is no GPL-like "copyleft" restriction. Distributing
44+
binary-only versions of Python, modified or not, is allowed. There
45+
is no requirement to release any of your source code. You can also
46+
write extension modules for Python and provide them only in binary
47+
form.
48+
49+
Famous projects released under a BSD-style license in the permissive
50+
sense of the last paragraph are the BSD operating system, python and
51+
TeX.
52+
53+
There are several reasons why early matplotlib developers selected a
54+
BSD compatible license. matplotlib is a python extension, and we
55+
choose a license that was based on the python license (BSD
56+
compatible). Also, we wanted to attract as many users and developers
57+
as possible, and many software companies will not use GPL code in
58+
software they plan to distribute, even those that are highly committed
59+
to open source development, such as `enthought
60+
<http://enthought.com>`_, out of legitimate concern that use of the
61+
GPL will "infect" their code base by its viral nature. In effect, they
62+
want to retain the right to release some proprietary code. Companies
63+
and institutions who use matplotlib often make significant
64+
contributions, because they have the resources to get a job done, even
65+
a boring one. Two of the matplotlib backends (FLTK and WX) were
66+
contributed by private companies. The final reason behind the
67+
licensing choice is compatibility with the other python extensions for
68+
scientific computing: ipython, numpy, scipy, the enthought tool suite
69+
and python itself are all distributed under BSD compatible licenses.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.