Skip to content

Commit 142435c

Browse files
tacaswelltacaswell
committed
DOC : Major work to FAQ pages and devel guide
closes #3115 closes #2198 - strengthen suggestion to use auto pep8 checker - added example minimal numpydoc docstring - formatting - tweaked suggested imports to make copy-paste easier - updated list of versions of python - github PR as primary mode of communication - Added map of major parts of a figure - removed reference to pythonbrew (which has been deprecated) - moved tox section to very end as the docs and the tox file are both very out of date.
1 parent 71dc35a commit 142435c

15 files changed

+237
-231
lines changed

‎doc/_templates/index.html

+7-13
Original file line numberDiff line numberDiff line change
@@ -63,18 +63,12 @@ <h1>Introduction</h1>
6363
For a sampling, see the <a href="{{ pathto('users/screenshots') }}">screenshots</a>, <a href="{{ pathto('gallery') }}">thumbnail</a> gallery, and
6464
<a href="examples/index.html">examples</a> directory</p>
6565

66-
<p>For example, using <tt>"%pylab"</tt> in the IPython shell for
67-
an interactive environment, to generate 10,000 gaussian random numbers
68-
and plot a histogram with 100 bins, you simply need to
69-
type</p>
70-
71-
<pre>
72-
x = randn(10000)
73-
hist(x, 100)</pre>
74-
75-
<p>For the power user, you have full control of line styles, font
76-
properties, axes properties, etc, via an object oriented interface
77-
or via a set of functions familiar to MATLAB users.</p>
66+
<p>For simple plotting the <pre>pyplot</pre> interface provides a
67+
MATLAB-like interface, particularly when combined
68+
with <pre>IPython</pre>. For the power user, you have full control
69+
of line styles, font properties, axes properties, etc, via an object
70+
oriented interface or via a set of functions familiar to MATLAB
71+
users.</p>
7872

7973
<div style="float: right; min-width: 450px; width: 50%; padding-left: 5%;">
8074
<h1>John Hunter (1968-2012)</h1>
@@ -124,7 +118,7 @@ <h1>Documentation</h1>
124118

125119
<h4>Other learning resources</h4>
126120

127-
<p>There are many <a href="{{ pathto('resources/index') }}">external learning
121+
<p>There are many <a href="{{ pathto('resources/index') }}">external learning
128122
resources</a> available including printed material, videos and tutorials.</p>
129123

130124
<h4>Need help?</h4>

‎doc/devel/coding_guide.rst

+34-7
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,9 @@ Style
3434
<http://www.python.org/dev/peps/pep-0008/>`_. Exceptions to these
3535
rules are acceptable if it makes the code objectively more readable.
3636

37-
- You may want to consider installing automatic PEP8 checking in
38-
your editor.
37+
- You should consider installing/enabling automatic PEP8 checking in your
38+
editor. Part of the test suite is checking PEP8 compliance, things
39+
go smoother if the code is mostly PEP8 compliant to begin with.
3940

4041
* No tabs (only spaces). No trailing whitespace.
4142

@@ -63,18 +64,44 @@ Documentation
6364
-------------
6465

6566
* Every new feature should be documented. If it's a new module, don't
66-
forget to add it to the API docs.
67+
forget to add a new rst file to the API docs.
6768

6869
* Docstrings should be in `numpydoc format
6970
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
7071
Don't be thrown off by the fact that many of the existing docstrings
71-
are not in that format. We are working to standardize on
72+
are not in that format; we are working to standardize on
7273
`numpydoc`.
7374

75+
Docstrings should look like (at a minimum)::
76+
77+
def foo(bar, baz=None):
78+
"""
79+
This is a prose description of foo and all the great
80+
things it does.
81+
82+
Parameters
83+
----------
84+
bar : (type of bar)
85+
A description of bar
86+
87+
baz : (type of baz), optional
88+
A description of baz
89+
90+
Returns
91+
-------
92+
foobar : (type of foobar)
93+
A description of foobar
94+
foobaz : (type of foobaz)
95+
A description of foobaz
96+
"""
97+
# some very clever code
98+
return foobar, foobaz
99+
100+
74101
* Each high-level plotting function should have a simple example in
75-
the `Example` section. This should be as simple as possible to
76-
demonstrate the method. More complex examples should go in the
77-
`examples` tree.
102+
the `Example` section of the docstring. This should be as simple as
103+
possible to demonstrate the method. More complex examples should go
104+
in the `examples` tree.
78105

79106
* Build the docs and make sure all formatting warnings are addressed.
80107

‎doc/devel/gitwash/branch_list.png

-13 KB
Binary file not shown.

‎doc/devel/gitwash/branch_list_compare.png

-10.4 KB
Binary file not shown.

‎doc/devel/gitwash/development_workflow.rst

+32-46
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,18 @@
44
Development workflow
55
====================
66

7+
You've discovered a bug or something else you want to change
8+
in matplotlib_ .. |emdash| excellent!
9+
10+
You've worked out a way to fix it |emdash| even better!
11+
12+
You want to tell us about it |emdash| best of all!
13+
14+
The easiest way to contribute to matplotlib_ is through github_. If
15+
for some reason you don't want to use github, see
16+
:ref:`making-patches` for instructions on how to email patches to the
17+
mailing list.
18+
719
You already have your own forked copy of the matplotlib_ repository, by
820
following :ref:`forking`, :ref:`set-up-fork`, and you have configured
921
git_ by following :ref:`configure-git`.
@@ -15,8 +27,10 @@ Workflow summary
1527
to the main matplotlib_ development repo. Your ``master`` then will follow
1628
the main matplotlib_ repository.
1729
* Start a new *feature branch* for each set of edits that you do.
18-
* If you can avoid it, try not to merge other branches into your feature
19-
branch while you are working.
30+
* Do not merge the ``master`` branch or maintenance tracking branches
31+
into your feature branch. If you need to include commits from upstream
32+
branches (either to pick up a bug fix or to resolve a conflict) please
33+
*rebase* your branch on the upstream branch.
2034
* Ask for review!
2135

2236
This way of working really helps to keep work well organized, and in
@@ -103,60 +117,32 @@ In more detail
103117
#. To push the changes up to your forked repo on github_, do a ``git
104118
push`` (see `git push`).
105119

106-
Asking for code review
107-
======================
108-
109-
#. Go to your repo URL |emdash| e.g.,
110-
``http://github.com/your-user-name/matplotlib``.
111-
#. Click on the *Branch list* button:
112-
113-
.. image:: branch_list.png
120+
Asking for code review |emdash| open a Pull Request (PR)
121+
========================================================
114122

115-
#. Click on the *Compare* button for your feature branch |emdash| here ``my-new-feature``:
116-
117-
.. image:: branch_list_compare.png
123+
It's a good idea to consult the :ref:`pull-request-checklist` to make
124+
sure your pull request is ready for merging.
118125

119-
#. If asked, select the *base* and *comparison* branch names you want to
120-
compare. Usually these will be ``master`` and ``my-new-feature``
121-
(where that is your feature branch name).
122-
#. At this point you should get a nice summary of the changes. Copy the
123-
URL for this, and post it to the `matplotlib mailing list`_, asking for
124-
review. The URL will look something like:
125-
``http://github.com/your-user-name/matplotlib/compare/master...my-new-feature``.
126-
There's an example at
127-
http://github.com/matthew-brett/nipy/compare/master...find-install-data
128-
See: http://github.com/blog/612-introducing-github-compare-view for
129-
more detail.
130126

131-
The generated comparison, is between your feature branch
132-
``my-new-feature``, and the place in ``master`` from which you branched
133-
``my-new-feature``. In other words, you can keep updating ``master``
134-
without interfering with the output from the comparison. More detail?
135-
Note the three dots in the URL above (``master...my-new-feature``) and
136-
see :ref:`dot2-dot3`.
127+
#. Go to your repo URL |emdash| e.g.,
128+
``http://github.com/your-user-name/matplotlib``.
137129

138-
It's a good idea to consult the :ref:`pull-request-checklist` to make
139-
sure your pull request is ready for merging.
130+
#. Select your feature branch from the drop down menu:
140131

141-
Asking for your changes to be merged into the main repo
142-
=======================================================
132+
#. Click on the green button:
143133

144-
When you are ready to ask for the merge of your code:
134+
#. Make sure that you are requesting a pull against the correct branch
145135

146-
#. Go to the URL of your forked repo, say
147-
``http://github.com/your-user-name/matplotlib.git``.
148-
#. Click on the 'Pull request' button:
136+
#. Enter a PR heading and description (if there is only one commit in
137+
the PR github will automatically fill these fields for you). If
138+
this PR is addressing a specific issue, please reference it by number
139+
(ex #1325) which github will automatically make into links.
149140

150-
.. image:: pull_button.png
141+
#. Click 'Create Pull Request' button!
151142

152-
Enter a message; we suggest you select only ``matplotlib`` as the
153-
recipient. The message will go to the `matplotlib mailing list`_. Please
154-
feel free to add others from the list as you like.
143+
#. Discussion of the change will take place in the pull request
144+
thread.
155145

156-
#. If the branch is to be merged into a maintenance branch on the main
157-
repo, make sure the "base branch" indicates the maintenance branch
158-
and not master. Github can not automatically determine the branch
159-
to merge into.
160146

161147
Staying up to date with changes in the central repository
162148
=========================================================

‎doc/devel/gitwash/forking_hell.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Create your own forked copy of matplotlib_
2626

2727
.. image:: forking_button.png
2828

29-
Now, after a short pause and some 'Hardcore forking action', you
30-
should find yourself at the home page for your own forked copy of matplotlib_.
29+
Now, after a short pause you should find yourself at the home page
30+
for your own forked copy of matplotlib_.
3131

3232
.. include:: links.inc

‎doc/devel/gitwash/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ Contents:
1111
git_intro
1212
git_install
1313
following_latest
14-
patching
1514
git_development
1615
git_resources
16+
patching

‎doc/devel/gitwash/patching.rst

-37
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,6 @@
22
Making a patch
33
================
44

5-
You've discovered a bug or something else you want to change
6-
in matplotlib_ .. |emdash| excellent!
7-
8-
You've worked out a way to fix it |emdash| even better!
9-
10-
You want to tell us about it |emdash| best of all!
11-
12-
The easiest way is to make a *patch* or set of patches. Here
13-
we explain how. Making a patch is the simplest and quickest,
14-
but if you're going to be doing anything more than simple
15-
quick things, please consider following the
16-
:ref:`git-development` model instead.
17-
185
.. _making-patches:
196

207
Making patches
@@ -107,28 +94,4 @@ code, just return to the ``master`` branch::
10794

10895
git checkout master
10996

110-
Moving from patching to development
111-
===================================
112-
113-
If you find you have done some patches, and you have one or
114-
more feature branches, you will probably want to switch to
115-
development mode. You can do this with the repository you
116-
have.
117-
118-
Fork the matplotlib_ repository on github_ |emdash| :ref:`forking`.
119-
Then::
120-
121-
# checkout and refresh master branch from main repo
122-
git checkout master
123-
git pull origin master
124-
# rename pointer to main repository to 'upstream'
125-
git remote rename origin upstream
126-
# point your repo to default read / write to your fork on github
127-
git remote add origin git@github.com:your-user-name/matplotlib.git
128-
# push up any branches you've made and want to keep
129-
git push origin the-fix-im-thinking-of
130-
131-
Then you can, if you want, follow the
132-
:ref:`development-workflow`.
133-
13497
.. include:: links.inc

‎doc/devel/gitwash/pull_button.png

-12.6 KB
Binary file not shown.

‎doc/devel/index.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _developers-guide-index:
22

3-
####################################
4-
The Matplotlib Developers' Guide
5-
####################################
3+
################################
4+
The Matplotlib Developers' Guide
5+
################################
66

77
.. htmlonly::
88

‎doc/devel/portable_code.rst

+4-3
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,17 @@ Welcome to the ``__future__``
1414

1515
The top of every `.py` file should include the following::
1616

17-
from __future__ import absolute_import, division, print_function, unicode_literals
17+
from __future__ import (absolute_import, division,
18+
print_function, unicode_literals)
19+
import six
1820

1921
This will make the Python 2 interpreter behave as close to Python 3 as
2022
possible.
2123

2224
All matplotlib files should also import `six`, whether they are using
2325
it or not, just to make moving code between modules easier, as `six`
24-
gets used *a lot*::
26+
gets used *a lot*.
2527

26-
import six
2728

2829
Finding places to use six
2930
^^^^^^^^^^^^^^^^^^^^^^^^^

0 commit comments

Comments
 (0)