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

Skip to content

Commit d52ce3b

Browse files
mdboommdboom
committed
Update with new developer docs
1 parent 398f229 commit d52ce3b

File tree

1,177 files changed

+1324
-1874
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,177 files changed

+1324
-1874
lines changed

‎_images/boxplot_demo_00.png

-50 Bytes

‎_images/boxplot_demo_01.png

-35 Bytes

‎_images/boxplot_demo_02.png

-207 Bytes

‎_images/boxplot_demo_03.png

1.03 KB

‎_images/boxplot_demo_04.png

-57 Bytes

‎_images/boxplot_demo_05.png

-53 Bytes

‎_images/boxplot_demo_06.png

-60 Bytes

‎_images/cohere_demo.png

-5.7 KB

‎_images/cohere_demo1.png

-5.7 KB

‎_images/contourf3d_demo2.png

-248 Bytes

‎_images/contourf3d_demo21.png

-248 Bytes

‎_images/contourf3d_demo22.png

-248 Bytes

‎_images/csd_demo.png

1.92 KB

‎_images/csd_demo1.png

1.92 KB

‎_images/demo_tight_layout_00_00.png

2.05 KB

‎_images/demo_tight_layout_00_01.png

614 Bytes

‎_images/demo_tight_layout_00_02.png

-4.3 KB

‎_images/demo_tight_layout_00_03.png

399 Bytes

‎_images/demo_tight_layout_00_04.png

1.7 KB

‎_images/demo_tight_layout_00_05.png

-852 Bytes

‎_images/demo_tight_layout_00_06.png

4.01 KB

‎_images/demo_tight_layout_01_00.png

2.37 KB

‎_images/finance_work2.png

257 Bytes

‎_images/finance_work21.png

257 Bytes

‎_images/parasite_simple2.png

-6 Bytes

‎_images/parasite_simple21.png

-2 Bytes

‎_images/plotmap.png

422 KB

‎_images/xcorr_demo.png

195 Bytes

‎_images/xcorr_demo1.png

195 Bytes

‎_sources/devel/coding_guide.txt

Lines changed: 89 additions & 481 deletions
Large diffs are not rendered by default.

‎_sources/devel/documenting_mpl.txt

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

‎_sources/devel/gitwash/development_workflow.txt

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

‎_sources/devel/index.txt

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

‎_sources/devel/release_guide.txt

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,6 @@ A guide for developers who are doing a matplotlib release
88

99
* Edit :file:`__init__.py` and bump the version number
1010

11-
12-
13-
When doing a release
14-
1511
.. _release-testing:
1612

1713
Testing
@@ -35,7 +31,7 @@ Testing
3531
.. _release-branching:
3632

3733
Branching
38-
============
34+
=========
3935

4036
Once all the tests are passing and you are ready to do a release, you
4137
need to create a release branch::
@@ -61,13 +57,16 @@ release after the fact, just track down the commit hash, and::
6157
Tags allow developers to quickly checkout different releases by name,
6258
and also provides source download via zip and tarball on github.
6359

60+
Then push the tags to the main repository::
61+
62+
git push upstream v1.0.1
63+
6464
.. _release-packaging:
6565

6666
Packaging
6767
=========
6868

69-
70-
* Make sure the :file:`MANIFEST.in` us up to date and remove
69+
* Make sure the :file:`MANIFEST.in` is up to date and remove
7170
:file:`MANIFEST` so it will be rebuilt by MANIFEST.in
7271

7372
* run `git clean` in the mpl git directory before building the sdist
@@ -102,6 +101,32 @@ there.
102101

103102
.. _release-announcing:
104103

104+
Documentation updates
105+
=====================
106+
107+
The built documentation exists in the `matplotlib.github.com
108+
<https://github.com/matplotlib/matplotlib.github.com/>`_ repository.
109+
Pushing changes to master automatically updates the website.
110+
111+
In the matplotlib source repository, build the documentation::
112+
113+
cd doc
114+
python make.py html
115+
python make.py latex
116+
117+
Then copy the build products into your local checkout of the
118+
`matplotlib.github.com` repository (assuming here to be checked out in
119+
`~/matplotlib.github.com`::
120+
121+
cp -r build/html/* ~/matplotlib.github.com
122+
cp build/latex/Matplotlib.pdf ~/matplotlib.github.com
123+
124+
Then, from the `matplotlib.github.com` directory, commit and push the
125+
changes upstream::
126+
127+
git commit -m "Updating for v1.0.1"
128+
git push upstream master
129+
105130
Announcing
106131
==========
107132

‎_sources/faq/howto_faq.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -757,8 +757,8 @@ Cite Matplotlib
757757

758758
If you want to refer to matplotlib in a publication, you can use
759759
"Matplotlib: A 2D Graphics Environment" by J. D. Hunter In Computing
760-
in Science & Engineering, Vol. 9, No. 3. (2007), pp. 90-95 (see `here
761-
<http://dx.doi.org/10.1109/MCSE.2007.55>`_)::
760+
in Science & Engineering, Vol. 9, No. 3. (2007), pp. 90-95 (see `this
761+
reference page <http://dx.doi.org/10.1109/MCSE.2007.55>`_)::
762762

763763
@article{Hunter:2007,
764764
Address = {10662 LOS VAQUEROS CIRCLE, PO BOX 3014, LOS ALAMITOS, CA 90720-1314 USA},

‎_sources/faq/troubleshooting_faq.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,13 +68,13 @@ Getting help
6868
There are a number of good resources for getting help with matplotlib.
6969
There is a good chance your question has already been asked:
7070

71-
- The `mailing list
71+
- The `mailing list archive
7272
<http://sourceforge.net/search/?group_id=80706&type_of_search=mlists>`_.
7373

7474
- `Github issues <https://github.com/matplotlib/matplotlib/issues>`_.
7575

7676
- Stackoverflow questions tagged `matplotlib
77-
<http://stackoverflow.com/questions/tagged/matplotlib>`_.
77+
<http://stackoverflow.com/questions/tagged/matplotlib>`_.
7878

7979
If you are unable to find an answer to your question through search,
8080
please provide the following information in your e-mail to the

‎_sources/users/license.txt

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ the `PSF <http://www.python.org/psf/license>`_ license. See the Open
1010
Source Initiative `licenses page
1111
<http://www.opensource.org/licenses>`_ for details on individual
1212
licenses. Non-BSD compatible licenses (eg LGPL) are acceptable in
13-
matplotlib :ref:`toolkits-index`. For a discussion of the motivations
14-
behind the licencing choice, see :ref:`license-discussion`.
13+
matplotlib toolkits. For a discussion of the motivations behind the
14+
licencing choice, see :ref:`license-discussion`.
1515

1616

1717
License agreement for matplotlib |version|
@@ -63,8 +63,3 @@ products or services of Licensee, or any third party.
6363
8. By copying, installing or otherwise using matplotlib |version|,
6464
Licensee agrees to be bound by the terms and conditions of this License
6565
Agreement.
66-
67-
68-
69-
70-

‎api/afm_api.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -350,7 +350,7 @@ <h3>Navigation</h3>
350350
</div>
351351
<div class="footer">
352352
&copy; Copyright 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the matplotlib development team.
353-
Last updated on Nov 13, 2012.
353+
Last updated on Nov 20, 2012.
354354
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
355355
</div>
356356
</body>

‎api/animation_api.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -569,7 +569,7 @@ <h3>Navigation</h3>
569569
</div>
570570
<div class="footer">
571571
&copy; Copyright 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the matplotlib development team.
572-
Last updated on Nov 13, 2012.
572+
Last updated on Nov 20, 2012.
573573
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
574574
</div>
575575
</body>

‎api/api_changes.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2183,7 +2183,7 @@ <h3>Navigation</h3>
21832183
</div>
21842184
<div class="footer">
21852185
&copy; Copyright 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the matplotlib development team.
2186-
Last updated on Nov 13, 2012.
2186+
Last updated on Nov 20, 2012.
21872187
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
21882188
</div>
21892189
</body>

‎api/artist_api.html

Lines changed: 34 additions & 35 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)