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

Skip to content

Commit 8ec5b2c

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

8 files changed

Lines changed: 485 additions & 719 deletions

File tree

‎doc/devel/coding_guide.rst‎

Lines changed: 84 additions & 483 deletions
Large diffs are not rendered by default.

‎doc/devel/documenting_mpl.rst‎

Lines 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‎

Lines 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‎

Lines 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‎

Lines 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)