DOC : Major work to FAQ pages and devel guide

closes matplotlib#3115
closes matplotlib#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.

Author: tacaswell

doc/_templates/index.html

@@ -63,18 +63,12 @@ <h1>Introduction</h1>
   For a sampling, see the <a href="{{ pathto('users/screenshots') }}">screenshots</a>, <a href="{{ pathto('gallery') }}">thumbnail</a> gallery,  and
     <a href="examples/index.html">examples</a> directory</p>
 
-  <p>For example, using <tt>"%pylab"</tt> in the IPython shell for
-  an interactive environment, to generate 10,000 gaussian random numbers
-  and plot a histogram with 100 bins, you simply need to
-  type</p>
-
-  <pre>
-  x = randn(10000)
-  hist(x, 100)</pre>
-
-  <p>For the power user, you have full control of line styles, font
-  properties, axes properties, etc, via an object oriented interface
-  or via a set of functions familiar to MATLAB users.</p>
+<p>For simple plotting the <pre>pyplot</pre> interface provides a
+  MATLAB-like interface, particularly when combined
+  with <pre>IPython</pre>.  For the power user, you have full control
+  of line styles, font properties, axes properties, etc, via an object
+  oriented interface or via a set of functions familiar to MATLAB
+  users.</p>
 
 <div style="float: right; min-width: 450px; width: 50%; padding-left: 5%;">
   <h1>John Hunter (1968-2012)</h1>
@@ -124,7 +118,7 @@ <h1>Documentation</h1>
 
   <h4>Other learning resources</h4>
 
-  <p>There are many <a href="{{ pathto('resources/index') }}">external learning 
+  <p>There are many <a href="{{ pathto('resources/index') }}">external learning
   resources</a> available including printed material, videos and tutorials.</p>
 
   <h4>Need help?</h4>

doc/devel/coding_guide.rst

@@ -34,8 +34,9 @@ Style
   <http://www.python.org/dev/peps/pep-0008/>`_.  Exceptions to these
   rules are acceptable if it makes the code objectively more readable.
 
-  - You may want to consider installing automatic PEP8 checking in
-    your editor.
+  - You should consider installing/enabling automatic PEP8 checking in your
+    editor.  Part of the test suite is checking PEP8 compliance, things
+    go smoother if the code is mostly PEP8 compliant to begin with.
 
 * No tabs (only spaces).  No trailing whitespace.
 
@@ -63,18 +64,44 @@ Documentation
 -------------
 
 * Every new feature should be documented.  If it's a new module, don't
-  forget to add it to the API docs.
+  forget to add a new rst file to the API docs.
 
 * Docstrings should be in `numpydoc format
   <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
   Don't be thrown off by the fact that many of the existing docstrings
-  are not in that format.  We are working to standardize on
+  are not in that format;  we are working to standardize on
   `numpydoc`.
 
+  Docstrings should look like (at a minimum)::
+
+        def foo(bar, baz=None):
+            """
+            This is a prose description of foo and all the great
+            things it does.
+
+            Parameters
+            ----------
+            bar : (type of bar)
+                A description of bar
+
+            baz : (type of baz), optional
+                A description of baz
+
+            Returns
+            -------
+            foobar : (type of foobar)
+                A description of foobar
+            foobaz : (type of foobaz)
+                A description of foobaz
+            """
+            # some very clever code
+            return foobar, foobaz
+
+
 * Each high-level plotting function should have a simple example in
-  the `Example` section.  This should be as simple as possible to
-  demonstrate the method.  More complex examples should go in the
-  `examples` tree.
+  the `Example` section of the docstring.  This should be as simple as
+  possible to demonstrate the method.  More complex examples should go
+  in the `examples` tree.
 
 * Build the docs and make sure all formatting warnings are addressed.
 

doc/devel/gitwash/branch_list.png

@@ -4,6 +4,18 @@
 Development workflow
 ====================
 
+You've discovered a bug or something else you want to change
+in matplotlib_ .. |emdash| excellent!
+
+You've worked out a way to fix it |emdash| even better!
+
+You want to tell us about it |emdash| best of all!
+
+The easiest way to contribute to matplotlib_ is through github_.  If
+for some reason you don't want to use github, see
+:ref:`making-patches` for instructions on how to email patches to the
+mailing list.
+
 You already have your own forked copy of the matplotlib_ repository, by
 following :ref:`forking`, :ref:`set-up-fork`, and you have configured
 git_ by following :ref:`configure-git`.
@@ -15,8 +27,10 @@ Workflow summary
   to the main matplotlib_ development repo.  Your ``master`` then will follow
   the main matplotlib_ repository.
 * Start a new *feature branch* for each set of edits that you do.
-* If you can avoid it, try not to merge other branches into your feature
-  branch while you are working.
+* Do not merge the ``master`` branch or maintenance tracking branches
+  into your feature branch.  If you need to include commits from upstream
+  branches (either to pick up a bug fix or to resolve a conflict) please
+  *rebase* your branch on the upstream branch.
 * Ask for review!
 
 This way of working really helps to keep work well organized, and in
@@ -103,60 +117,32 @@ In more detail
 #. To push the changes up to your forked repo on github_, do a ``git
    push`` (see `git push`).
 
-Asking for code review
-======================
-
-#. Go to your repo URL |emdash| e.g.,
-   ``http://github.com/your-user-name/matplotlib``.
-#. Click on the *Branch list* button:
-
-   .. image:: branch_list.png
+Asking for code review |emdash| open a Pull Request (PR)
+========================================================
 
-#. Click on the *Compare* button for your feature branch |emdash| here ``my-new-feature``:
-
-   .. image:: branch_list_compare.png
+It's a good idea to consult the :ref:`pull-request-checklist` to make
+sure your pull request is ready for merging.
 
-#. If asked, select the *base* and *comparison* branch names you want to
-   compare.  Usually these will be ``master`` and ``my-new-feature``
-   (where that is your feature branch name).
-#. At this point you should get a nice summary of the changes.  Copy the
-   URL for this, and post it to the `matplotlib mailing list`_, asking for
-   review.  The URL will look something like:
-   ``http://github.com/your-user-name/matplotlib/compare/master...my-new-feature``.
-   There's an example at
-   http://github.com/matthew-brett/nipy/compare/master...find-install-data
-   See: http://github.com/blog/612-introducing-github-compare-view for
-   more detail.
 
-The generated comparison, is between your feature branch
-``my-new-feature``, and the place in ``master`` from which you branched
-``my-new-feature``.  In other words, you can keep updating ``master``
-without interfering with the output from the comparison.  More detail?
-Note the three dots in the URL above (``master...my-new-feature``) and
-see :ref:`dot2-dot3`.
+#. Go to your repo URL |emdash| e.g.,
+   ``http://github.com/your-user-name/matplotlib``.
 
-It's a good idea to consult the :ref:`pull-request-checklist` to make
-sure your pull request is ready for merging.
+#. Select your feature branch from the drop down menu:
 
-Asking for your changes to be merged into the main repo
-=======================================================
+#. Click on the green button:
 
-When you are ready to ask for the merge of your code:
+#. Make sure that you are requesting a pull against the correct branch
 
-#. Go to the URL of your forked repo, say
-   ``http://github.com/your-user-name/matplotlib.git``.
-#. Click on the 'Pull request' button:
+#. Enter a PR heading and description (if there is only one commit in
+   the PR github will automatically fill these fields for you).  If
+   this PR is addressing a specific issue, please reference it by number
+   (ex #1325) which github will automatically make into links.
 
-   .. image:: pull_button.png
+#. Click 'Create Pull Request' button!
 
-   Enter a message; we suggest you select only ``matplotlib`` as the
-   recipient.  The message will go to the `matplotlib mailing list`_.  Please
-   feel free to add others from the list as you like.
+#. Discussion of the change will take place in the pull request
+   thread.
 
-#. If the branch is to be merged into a maintenance branch on the main
-   repo, make sure the "base branch" indicates the maintenance branch
-   and not master.  Github can not automatically determine the branch
-   to merge into.
 
 Staying up to date with changes in the central repository
 =========================================================

doc/devel/gitwash/branch_list_compare.png

@@ -26,7 +26,7 @@ Create your own forked copy of matplotlib_
 
    .. image:: forking_button.png
 
-   Now, after a short pause and some 'Hardcore forking action', you
-   should find yourself at the home page for your own forked copy of matplotlib_.
+   Now, after a short pause you should find yourself at the home page
+   for your own forked copy of matplotlib_.
 
 .. include:: links.inc

doc/devel/gitwash/development_workflow.rst

@@ -11,6 +11,6 @@ Contents:
    git_intro
    git_install
    following_latest
-   patching
    git_development
    git_resources
+   patching

doc/devel/gitwash/forking_hell.rst

@@ -2,19 +2,6 @@
  Making a patch
 ================
 
-You've discovered a bug or something else you want to change
-in matplotlib_ .. |emdash| excellent!
-
-You've worked out a way to fix it |emdash| even better!
-
-You want to tell us about it |emdash| best of all!
-
-The easiest way is to make a *patch* or set of patches.  Here
-we explain how.  Making a patch is the simplest and quickest,
-but if you're going to be doing anything more than simple
-quick things, please consider following the
-:ref:`git-development` model instead.
-
 .. _making-patches:
 
 Making patches
@@ -107,28 +94,4 @@ code, just return to the ``master`` branch::
 
    git checkout master
 
-Moving from patching to development
-===================================
-
-If you find you have done some patches, and you have one or
-more feature branches, you will probably want to switch to
-development mode.  You can do this with the repository you
-have.
-
-Fork the matplotlib_ repository on github_ |emdash| :ref:`forking`.
-Then::
-
-   # checkout and refresh master branch from main repo
-   git checkout master
-   git pull origin master
-   # rename pointer to main repository to 'upstream'
-   git remote rename origin upstream
-   # point your repo to default read / write to your fork on github
-   git remote add origin [email protected]:your-user-name/matplotlib.git
-   # push up any branches you've made and want to keep
-   git push origin the-fix-im-thinking-of
-
-Then you can, if you want, follow the
-:ref:`development-workflow`.
-
 .. include:: links.inc

doc/devel/gitwash/index.rst

@@ -1,8 +1,8 @@
 .. _developers-guide-index:
 
-####################################
-  The Matplotlib Developers' Guide
-####################################
+################################
+The Matplotlib Developers' Guide
+################################
 
 .. htmlonly::