diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 63894ab29370..664e92fcf14e 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -63,18 +63,12 @@

Introduction

For a sampling, see the screenshots, thumbnail gallery, and examples directory

-

For example, using "%pylab" 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

- - 
-  x = randn(10000)
-  hist(x, 100)
- -

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.

+

For simple plotting the 

pyplot
interface provides a + MATLAB-like interface, particularly when combined + with 
IPython
. 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.

John Hunter (1968-2012)

@@ -124,7 +118,7 @@

Documentation

Other learning resources

-

There are many external learning +

There are many external learning resources available including printed material, videos and tutorials.

Need help?

diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 646f6d4c09d0..cd12a126942a 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -34,8 +34,9 @@ Style `_. 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 `_. 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. diff --git a/doc/devel/gitwash/branch_list.png b/doc/devel/gitwash/branch_list.png deleted file mode 100644 index 1196eb754d36..000000000000 Binary files a/doc/devel/gitwash/branch_list.png and /dev/null differ diff --git a/doc/devel/gitwash/branch_list_compare.png b/doc/devel/gitwash/branch_list_compare.png deleted file mode 100644 index 336afa374604..000000000000 Binary files a/doc/devel/gitwash/branch_list_compare.png and /dev/null differ diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 2ef9ecbfb42a..0276423e8c6c 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -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 ========================================================= diff --git a/doc/devel/gitwash/forking_hell.rst b/doc/devel/gitwash/forking_hell.rst index 350d50e7fccf..261ae775d7dc 100644 --- a/doc/devel/gitwash/forking_hell.rst +++ b/doc/devel/gitwash/forking_hell.rst @@ -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 diff --git a/doc/devel/gitwash/index.rst b/doc/devel/gitwash/index.rst index 48053bc19b71..c9567cc7e359 100644 --- a/doc/devel/gitwash/index.rst +++ b/doc/devel/gitwash/index.rst @@ -11,6 +11,6 @@ Contents: git_intro git_install following_latest - patching git_development git_resources + patching diff --git a/doc/devel/gitwash/patching.rst b/doc/devel/gitwash/patching.rst index 6f7733125c88..fb42e1ef3af3 100644 --- a/doc/devel/gitwash/patching.rst +++ b/doc/devel/gitwash/patching.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 git@github.com: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 diff --git a/doc/devel/gitwash/pull_button.png b/doc/devel/gitwash/pull_button.png deleted file mode 100644 index e5031681b97b..000000000000 Binary files a/doc/devel/gitwash/pull_button.png and /dev/null differ diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 47ad4fa7ba1c..5b3c01eebd5a 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -1,8 +1,8 @@ .. _developers-guide-index: -#################################### - The Matplotlib Developers' Guide -#################################### +################################ +The Matplotlib Developers' Guide +################################ .. htmlonly:: diff --git a/doc/devel/portable_code.rst b/doc/devel/portable_code.rst index dd1f9f3dd6cd..a557905fa6dc 100644 --- a/doc/devel/portable_code.rst +++ b/doc/devel/portable_code.rst @@ -14,16 +14,17 @@ Welcome to the ``__future__`` The top of every `.py` file should include the following:: - from __future__ import absolute_import, division, print_function, unicode_literals + from __future__ import (absolute_import, division, + print_function, unicode_literals) + import six This will make the Python 2 interpreter behave as close to Python 3 as possible. All matplotlib files should also import `six`, whether they are using it or not, just to make moving code between modules easier, as `six` -gets used *a lot*:: +gets used *a lot*. - import six Finding places to use six ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 7d778041c68a..f29d7be30175 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -42,13 +42,20 @@ a colon, e.g., (this is assuming the test is installed):: python tests.py matplotlib.tests.test_simplification:test_clipping +If you want to run the full test suite, but want to save wall time try running the +tests in parallel:: + + python ../matplotlib/tests.py -sv --processes=5 --process-timeout=300 + +as we do on Travis.ci. + + An alternative implementation that does not look at command line arguments works from within Python:: import matplotlib matplotlib.test() - .. _`nosetest arguments`: http://somethingaboutorange.com/mrl/projects/nose/1.0.0/usage.html @@ -177,6 +184,36 @@ to add tests for it in ``matplotlib.tests.test_whizbang``. To add this module to the list of default tests, append its name to ``default_test_modules`` in :file:`lib/matplotlib/__init__.py`. +Using Travis CI +--------------- + +`Travis CI `_ is a hosted CI system "in the +cloud". + +Travis is configured to receive notifications of new commits to GitHub +repos (via GitHub "service hooks") and to run builds or tests when it +sees these new commits. It looks for a YAML file called +``.travis.yml`` in the root of the repository to see how to test the +project. + +Travis CI is already enabled for the `main matplotlib GitHub +repository `_ -- for +example, see `its Travis page +`_. + +If you want to enable Travis CI for your personal matplotlib GitHub +repo, simply enable the repo to use Travis CI in either the Travis CI +UI or the GitHub UI (Admin | Service Hooks). For details, see `the +Travis CI Getting Started page +`_. This +generally isn't necessary, since any pull request submitted against +the main matplotlib repository will be tested. + +Once this is configured, you can see the Travis CI results at +http://travis-ci.org/#!/your_GitHub_user_name/matplotlib -- here's `an +example `_. + + Using tox --------- @@ -185,11 +222,10 @@ multiple Python environments, including multiple versions of Python (e.g., 2.6, 2.7, 3.2, etc.) and even different Python implementations altogether (e.g., CPython, PyPy, Jython, etc.) -Testing all 4 versions of Python (2.6, 2.7, 3.1, and 3.2) requires -having four versions of Python installed on your system and on the +Testing all versions of Python (2.6, 2.7, 3.*) requires +having multiple versions of Python installed on your system and on the PATH. Depending on your operating system, you may want to use your -package manager (such as apt-get, yum or MacPorts) to do this, or use -`pythonbrew `_. +package manager (such as apt-get, yum or MacPorts) to do this. tox makes it easy to determine if your working copy introduced any regressions before submitting a pull request. Here's how to use it: @@ -220,32 +256,3 @@ edit this file if you want to add new environments to test (e.g., tests are run. For more info on the ``tox.ini`` file, see the `Tox Configuration Specification `_. - -Using Travis CI ---------------- - -`Travis CI `_ is a hosted CI system "in the -cloud". - -Travis is configured to receive notifications of new commits to GitHub -repos (via GitHub "service hooks") and to run builds or tests when it -sees these new commits. It looks for a YAML file called -``.travis.yml`` in the root of the repository to see how to test the -project. - -Travis CI is already enabled for the `main matplotlib GitHub -repository `_ -- for -example, see `its Travis page -`_. - -If you want to enable Travis CI for your personal matplotlib GitHub -repo, simply enable the repo to use Travis CI in either the Travis CI -UI or the GitHub UI (Admin | Service Hooks). For details, see `the -Travis CI Getting Started page -`_. This -generally isn't necessary, since any pull request submitted against -the main matplotlib repository will be tested. - -Once this is configured, you can see the Travis CI results at -http://travis-ci.org/#!/your_GitHub_user_name/matplotlib -- here's `an -example `_. diff --git a/doc/faq/fig_map.png b/doc/faq/fig_map.png new file mode 100644 index 000000000000..8af3500399fd Binary files /dev/null and b/doc/faq/fig_map.png differ diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst index 9b391fb7aac5..983b2e5f840e 100644 --- a/doc/faq/howto_faq.rst +++ b/doc/faq/howto_faq.rst @@ -1,3 +1,4 @@ + .. _howto-faq: ****** @@ -11,7 +12,7 @@ How-To .. _howto-plotting: Plotting: howto -================= +=============== .. _howto-findobj: @@ -53,7 +54,7 @@ formatter. See :mod:`~matplotlib.ticker` for details. .. _howto-transparent: Save transparent figures ----------------------------------- +------------------------ The :meth:`~matplotlib.pyplot.savefig` command has a keyword argument *transparent* which, if 'True', will make the figure and axes @@ -113,7 +114,7 @@ Finally, the multipage pdf object has to be closed:: .. _howto-subplots-adjust: Move the edge of an axes to make room for tick labels ----------------------------------------------------------------------------- +----------------------------------------------------- For subplots, you can control the default spacing on the left, right, bottom, and top as well as the horizontal and vertical spacing between @@ -322,53 +323,6 @@ some ratio which controls the ratio:: See :ref:`pylab_examples-equal_aspect_ratio` for a complete example. -.. _howto-movie: - -Make a movie ------------- - -If you want to take an animated plot and turn it into a movie, the -best approach is to save a series of image files (eg PNG) and use an -external tool to convert them to a movie. You can use `mencoder -`_, -which is part of the `mplayer `_ suite -for this:: - - #fps (frames per second) controls the play speed - mencoder 'mf://*.png' -mf type=png:fps=10 -ovc \\ - lavc -lavcopts vcodec=wmv2 -oac copy -o animation.avi - -The swiss army knife of image tools, ImageMagick's `convert -`_ works for this as -well. - -Here is a simple example script that saves some PNGs, makes them into -a movie, and then cleans up:: - - import os, sys - import matplotlib.pyplot as plt - - files = [] - fig = plt.figure(figsize=(5,5)) - ax = fig.add_subplot(111) - for i in range(50): # 50 frames - ax.cla() - ax.imshow(rand(5,5), interpolation='nearest') - fname = '_tmp%03d.png'%i - print 'Saving frame', fname - fig.savefig(fname) - files.append(fname) - - print 'Making movie animation.mpg - this make take a while' - os.system("mencoder 'mf://_tmp*.png' -mf type=png:fps=10 \\ - -ovc lavc -lavcopts vcodec=wmv2 -oac copy -o animation.mpg") - -.. htmlonly:: - - Josh Lifton provided this example :ref:`old_animation-movie_demo`, which - is possibly dated since it was written in 2004. - - .. _howto-twoscale: Multiple y-axis scales @@ -437,7 +391,7 @@ pyplot:: .. _howto-show: Use :func:`~matplotlib.pyplot.show` ------------------------------------------- +----------------------------------- When you want to view your plots on your display, the user interface backend will need to start the GUI mainloop. @@ -527,39 +481,42 @@ though we have made significant progress towards supporting blocking events. Contributing: howto =================== +.. _how-to-request-feature: + +Request a new feature +--------------------- + +Is there a feature you wish matplotlib had? Then ask! The best +way to get started is to email the developer `mailing +list `_ for discussion. +This is an open source project developed primarily in the +contributors free time, so there is no guarantee that your +feature will be added. The *best* way to get the feature +you need added is to contribute it your self. + .. _how-to-submit-patch: -Submit a patch --------------- - -See :ref:`making-patches` for information on how to make a patch with git. - -If you are posting a patch to fix a code bug, please explain your -patch in words -- what was broken before and how you fixed it. Also, -even if your patch is particularly simple, just a few lines or a -single function replacement, we encourage people to submit git diffs -against HEAD of the branch they are patching. It just makes life -easier for us, since we (fortunately) get a lot of contributions, and -want to receive them in a standard format. If possible, for any -non-trivial change, please include a complete, free-standing example -that the developers can run unmodified which shows the undesired -behavior pre-patch and the desired behavior post-patch, with a clear -verbal description of what to look for. A developer may -have written the function you are working on years ago, and may no -longer be with the project, so it is quite possible you are the world -expert on the code you are patching and we want to hear as much detail -as you can offer. - -When emailing your patch and examples, feel free to paste any code -into the text of the message, indeed we encourage it, but also attach -the patches and examples since many email clients screw up the -formatting of plain text, and we spend lots of needless time trying to -reformat the code to make it usable. - -You should check out the guide to developing matplotlib to make sure -your patch abides by our coding conventions -:ref:`developers-guide-index`. +Reporting a bug or submitting a patch +------------------------------------- + +The development of matplotlib is organized through `github +`_. If you would like +to report a bug or submit a patch please use that interface. + +To report a bug `create an issue +`_ on github +(this requires having a github account). Please include a `Short, +Self Contained, Correct (Compilable), Example `_ +demonstrating what the bug is. Including a clear, easy to test +example makes it easy for the developers to evaluate the bug. Expect +that the bug reports will be a conversation. If you do not want to +register with github, please email bug reports to the `mailing list +`_. + +The easiest way to submit patches to matplotlib is through pull +requests on github. Please see the :ref:`developers-guide-index` for +the details. .. _how-to-contribute-docs: @@ -605,7 +562,8 @@ your documents. Once your documentation contributions are working (and hopefully tested by actually *building* the docs) you can submit them as a patch against git. See :ref:`install-git` and :ref:`how-to-submit-patch`. -Looking for something to do? Search for `TODO <../search.html?q=todo>`_. +Looking for something to do? Search for `TODO <../search.html?q=todo>`_ +or look at the open issues on github. @@ -692,9 +650,8 @@ Andrew Dalke of `Dalke Scientific `_ has written a nice `article `_ on how to make html click maps with matplotlib agg PNGs. We would -also like to add this functionality to SVG and add a SWF backend to -support these kind of images. If you are interested in contributing -to these efforts that would be great. +also like to add this functionality to SVG. If you are interested in +contributing to these efforts that would be great. .. _how-to-search-examples: diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index 731c4c6d2d8e..4f57606d83a0 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -46,6 +46,75 @@ For even more control -- which is essential for things like embedding matplotlib plots in GUI applications -- the pyplot level may be dropped completely, leaving a purely object-oriented approach. +.. _figure_parts: + +Parts of a Figure +================= +.. image:: fig_map.png + +:class:`~matplotlib.figure.Figure` +---------------------------------- + +The **whole** figure (marked as the outer red box). The figure keeps +track of all the child :class:`~matplotlib.axes.Axes`, a smattering of +'special' artists (titles, figure legends, etc), and the **canvas**. +(Don't worry too much about the canvas, it is crucial as it is the +object that actually does the drawing to get you your plot, but as the +user it is more-or-less invisible to you). A figure can have any +number of :class:`~matplotlib.axes.Axes`, but to be useful should have +at least one. + +The easiest way to create a new figure is with pyplot:: + + fig = plt.figure() # an empty figure with no axes + fig, ax_lst = plt.subplots(2, 2) # a figure with a 2x2 grid of Axes + + +:class:`~matplotlib.axes.Axes` +------------------------------ + +This is what you think of as 'a plot', it is the region of the image +with the data space (marked as the inner blue box). A given figure +can contain many Axes, but a given :class:`~matplotlib.axes.Axes` +object can only be in one :class:`~matplotlib.figure.Figure`. The +Axes contains two (or three in the case of 3D) +:class:`~matplotlib.axis.Axis` objects (be aware of the difference +between **Axes** and **Axis**) which take care of the data limits (the +data limits can also be controlled via set via the +:meth:`~matplotlib.axes.Axes.set_xlim` and +:meth:`~matplotlib.axes.Axes.set_ylim` :class:`Axes` methods). Each +:class:`Axes` has a title (set via +:meth:`~matplotlib.axes.Axes.set_title`), an x-label (set via +:meth:`~matplotlib.axes.Axes.set_xlabel`), and a y-label set via +:meth:`~matplotlib.axes.Axes.set_ylabel`). + +The :class:`Axes` class and it's member functions are the primary entry +point to working with the OO interface. + +:class:`~matplotlib.axis.Axis` +------------------------------ + +These are the number-line-like objects (circled in green). They take +care of setting the graph limits and generating the ticks (the marks +on the axis) and ticklabels (strings labeling the ticks). The +location of the ticks is determined by a +:class:`~matplotlib.ticker.Locator` object and the ticklabel strings +are formatted by a :class:`~matplotlib.ticker.Formatter`. The +combination of the correct :class:`Locator` and :class:`Formatter` gives +very fine control over the tick locations and labels. + +:class:`~matplotlib.artist.Artist` +---------------------------------- + +Basically everything you can see on the figure is an artist (even the +:class:`Figure`, :class:`Axes`, and :class:`Axis` objects). This +includes :class:`Text` objects, :class:`Line2D` objects, +:class:`collection` objects, :class:`Patch` objects ... (you get the +idea). When the figure is rendered, all of the artists are drawn to +the **canvas**. Most Artists are tied to an Axes; such an Artist +cannot be shared by multiple Axes, or moved from one to another. + + .. _pylab: Matplotlib, pyplot and pylab: how are they related? @@ -177,6 +246,7 @@ which you would then use as:: fig, ax = plt.subplots(1, 1) my_plotter(ax, data1, data2, {'marker':'x'}) + or if you wanted to have 2 sub-plots:: fig, (ax1, ax2) = plt.subplots(1, 2)