diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index a9a7089f239c..0b5bce477ede 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -357,6 +357,19 @@ div.admonition, div.warning { font-size: 0.9em; } +div.warning { + color: #b94a48; + background-color: #F3E5E5; + border: 1px solid #eed3d7; +} + +div.green { + color: #468847; + background-color: #dff0d8; + border: 1px solid #d6e9c6; +} + + div.admonition p, div.warning p { margin: 0.5em 1em 0.5em 1em; padding: 0; @@ -366,6 +379,11 @@ div.admonition pre, div.warning pre { margin: 0.4em 1em 0.4em 1em; } +div.admonition p.admonition-title + p { + display: inline; +} + + div.admonition p.admonition-title, div.warning p.admonition-title { margin: 0; @@ -373,12 +391,45 @@ div.warning p.admonition-title { font-size: 14px; } +div.admonition { + margin-bottom: 10px; + margin-top: 10px; + padding: 7px; + border-radius: 4px; + -moz-border-radius: 4px; + } + + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.topic { + background-color: #eee; + border: 1px solid #CCC; + margin: 10px 0px; + padding: 7px 7px 0px; + border-radius: 4px; + -moz-border-radius: 4px; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; +} + +div.seealso { + background-color: #FFFBE8; + border: 1px solid #fbeed5; + color: #AF8A4B; + } + div.warning { border: 1px solid #940000; } div.warning p.admonition-title { - background-color: #CF0000; border-bottom-color: #940000; } diff --git a/doc/api/index.rst b/doc/api/index.rst index 8d8892834c73..23a5e41a2325 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -51,6 +51,7 @@ text_api.rst ticker_api.rst tight_layout_api.rst + transformations.rst tri_api.rst type1font.rst units_api.rst diff --git a/doc/devel/transformations.rst b/doc/api/transformations.rst similarity index 100% rename from doc/devel/transformations.rst rename to doc/api/transformations.rst diff --git a/doc/devel/add_new_projection.rst b/doc/devel/add_new_projection.rst index b05e05f5fc9a..9ef7c8f27ac0 100644 --- a/doc/devel/add_new_projection.rst +++ b/doc/devel/add_new_projection.rst @@ -1,8 +1,8 @@ .. _adding-new-scales: -*********************************************** -Adding new scales and projections to matplotlib -*********************************************** +========================================================= +Developer's guide for creating scales and transformations +========================================================= .. ::author Michael Droettboom diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 04edfb919417..8ff8508e0621 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -1,64 +1,24 @@ -.. _coding-guide: +.. _reviewers-guide: -************ -Coding guide -************ +******************** +Reviewers guideline +******************** .. _pull-request-checklist: Pull request checklist ====================== -This checklist should be consulted when creating pull requests to make -sure they are complete before merging. These are not intended to be -rigidly followed---it's just an attempt to list in one place all of -the items that are necessary for a good pull request. Of course, some -items will not always apply. - Branch selection ---------------- * In general, simple bugfixes that are unlikely to introduce new bugs of their own should be merged onto the maintenance branch. New features, or anything that changes the API, should be made against - master. The rules are fuzzy here -- when in doubt, try to get some - consensus. - - * Once changes are merged into the maintenance branch, they should - be merged into master. - -Style ------ - -* Formatting should follow `PEP8 - `_. Exceptions to these - rules are acceptable if it makes the code objectively more readable. - - - 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. + master. The rules are fuzzy here -- when in doubt, target master. - - Configuring your editor to remove these things upon saving will - save a lot of trouble. - -* Import the following modules using the standard scipy conventions:: - - import numpy as np - import numpy.ma as ma - import matplotlib as mpl - from matplotlib import pyplot as plt - import matplotlib.cbook as cbook - import matplotlib.collections as mcol - import matplotlib.patches as mpatches - -* See below for additional points about - :ref:`keyword-argument-processing`, if code in your pull request - does that. - -* Adding a new pyplot function involves generating code. See - :ref:`new-pyplot-function` for more information. +* Once changes are merged into the maintenance branch, they should + be merged into master. Documentation ------------- @@ -66,38 +26,6 @@ Documentation * Every new feature should be documented. If it's a new module, don't 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 - `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 of the docstring. This should be as simple as possible to demonstrate the method. More complex examples should go @@ -116,55 +44,6 @@ Documentation * If you change the API in a backward-incompatible way, please document it in :file:`doc/api/api_changes.rst`. -Testing -------- - -Using the test framework is discussed in detail in the section -:ref:`testing`. - -* If the PR is a bugfix, add a test that fails prior to the change and - passes with the change. Include any relevant issue numbers in the - docstring of the test. - -* If this is a new feature, add a test that exercises as much of the - new feature as possible. (The `--with-coverage` option may be - useful here). - -* Make sure the Travis tests are passing before merging. - - - The Travis tests automatically test on all of the Python versions - matplotlib supports whenever a pull request is created or updated. - The `tox` support in matplotlib may be useful for testing locally. - -Installation ------------- - -* If you have added new files or directories, or reorganized existing - ones, make sure the new files included in the match patterns in - :file:`MANIFEST.in`, and/or in `package_data` in `setup.py`. - -C/C++ extensions ----------------- - -* Extensions may be written in C or C++. - -* Code style should conform to PEP7 (understanding that PEP7 doesn't - address C++, but most of its admonitions still apply). - -* Interfacing with Python may be done either with the raw Python/C API - or Cython. - -* Python/C interface code should be kept separate from the core C/C++ - code. The interface code should be named `FOO_wrap.cpp` or - `FOO_wrapper.cpp`. - -* Header file documentation (aka docstrings) should be in Numpydoc - format. We don't plan on using automated tools for these - docstrings, and the Numpydoc format is well understood in the - scientific Python community. - - - PR Review guidelines ==================== @@ -182,6 +61,12 @@ PR Review guidelines 'approve review'). If you do the merge please removed the ``'[MRG+N']`` prefix. +* Make sure the Travis tests are passing before merging. + + - The Travis tests automatically test on all of the Python versions + matplotlib supports whenever a pull request is created or updated. + The `tox` support in matplotlib may be useful for testing locally. + * Do not self merge, except for 'small' patches to un-break the CI. * Squashing is case-by-case. The balance is between burden on the @@ -224,165 +109,3 @@ the merge notification) or through the git CLI tools.:: # from the cherry-pick + branch it was moved to These commands work on git 2.7.1. - - -Style guide -=========== - -.. _keyword-argument-processing: - -Keyword argument processing ---------------------------- - -Matplotlib makes extensive use of ``**kwargs`` for pass-through -customizations from one function to another. A typical example is in -:func:`matplotlib.pylab.text`. The definition of the pylab text -function is a simple pass-through to -:meth:`matplotlib.axes.Axes.text`:: - - # in pylab.py - def text(*args, **kwargs): - ret = gca().text(*args, **kwargs) - draw_if_interactive() - return ret - -:meth:`~matplotlib.axes.Axes.text` in simplified form looks like this, -i.e., it just passes all ``args`` and ``kwargs`` on to -:meth:`matplotlib.text.Text.__init__`:: - - # in axes.py - def text(self, x, y, s, fontdict=None, withdash=False, **kwargs): - t = Text(x=x, y=y, text=s, **kwargs) - -and :meth:`~matplotlib.text.Text.__init__` (again with liberties for -illustration) just passes them on to the -:meth:`matplotlib.artist.Artist.update` method:: - - # in text.py - def __init__(self, x=0, y=0, text='', **kwargs): - Artist.__init__(self) - self.update(kwargs) - -``update`` does the work looking for methods named like -``set_property`` if ``property`` is a keyword argument. i.e., no one -looks at the keywords, they just get passed through the API to the -artist constructor which looks for suitably named methods and calls -them with the value. - -As a general rule, the use of ``**kwargs`` should be reserved for -pass-through keyword arguments, as in the example above. If all the -keyword args are to be used in the function, and not passed -on, use the key/value keyword args in the function definition rather -than the ``**kwargs`` idiom. - -In some cases, you may want to consume some keys in the local -function, and let others pass through. You can ``pop`` the ones to be -used locally and pass on the rest. For example, in -:meth:`~matplotlib.axes.Axes.plot`, ``scalex`` and ``scaley`` are -local arguments and the rest are passed on as -:meth:`~matplotlib.lines.Line2D` keyword arguments:: - - # in axes.py - def plot(self, *args, **kwargs): - scalex = kwargs.pop('scalex', True) - scaley = kwargs.pop('scaley', True) - if not self._hold: self.cla() - lines = [] - for line in self._get_lines(*args, **kwargs): - self.add_line(line) - lines.append(line) - -Note: there is a use case when ``kwargs`` are meant to be used locally -in the function (not passed on), but you still need the ``**kwargs`` -idiom. That is when you want to use ``*args`` to allow variable -numbers of non-keyword args. In this case, python will not allow you -to use named keyword args after the ``*args`` usage, so you will be -forced to use ``**kwargs``. An example is -:meth:`matplotlib.contour.ContourLabeler.clabel`:: - - # in contour.py - def clabel(self, *args, **kwargs): - fontsize = kwargs.get('fontsize', None) - inline = kwargs.get('inline', 1) - self.fmt = kwargs.get('fmt', '%1.3f') - colors = kwargs.get('colors', None) - if len(args) == 0: - levels = self.levels - indices = range(len(self.levels)) - elif len(args) == 1: - ...etc... - -Hints -===== - -This section describes how to add certain kinds of new features to -matplotlib. - -.. _custom_backend: - -Developing a new backend ------------------------- - -If you are working on a custom backend, the *backend* setting in -:file:`matplotlibrc` (:ref:`customizing-matplotlib`) supports an -external backend via the ``module`` directive. if -:file:`my_backend.py` is a matplotlib backend in your -:envvar:`PYTHONPATH`, you can set use it on one of several ways - -* in matplotlibrc:: - - backend : module://my_backend - - -* with the :envvar:`MPLBACKEND` environment variable:: - - > export MPLBACKEND="module://my_backend" - > python simple_plot.py - -* from the command shell with the `-d` flag:: - - > python simple_plot.py -dmodule://my_backend - -* with the use directive in your script:: - - import matplotlib - matplotlib.use('module://my_backend') - -.. _sample-data: - -Writing examples ----------------- - -We have hundreds of examples in subdirectories of -:file:`matplotlib/examples`, and these are automatically generated -when the website is built to show up both in the `examples -<../examples/index.html>`_ and `gallery -<../gallery.html>`_ sections of the website. - -Any sample data that the example uses should be kept small and -distributed with matplotlib in the -`lib/matplotlib/mpl-data/sample_data/` directory. Then in your -example code you can load it into a file handle with:: - - import matplotlib.cbook as cbook - fh = cbook.get_sample_data('mydata.dat') - -.. _new-pyplot-function: - -Writing a new pyplot function ------------------------------ - -A large portion of the pyplot interface is automatically generated by the -`boilerplate.py` script (in the root of the source tree). To add or remove -a plotting method from pyplot, edit the appropriate list in `boilerplate.py` -and then run the script which will update the content in -`lib/matplotlib/pyplot.py`. Both the changes in `boilerplate.py` and -`lib/matplotlib/pyplot.py` should be checked into the repository. - -Note: boilerplate.py looks for changes in the installed version of matplotlib -and not the source tree. If you expect the pyplot.py file to show your new -changes, but they are missing, this might be the cause. - -Install your new files by running `python setup.py build` and `python setup.py -install` followed by `python boilerplate.py`. The new pyplot.py file should now -have the latest changes. diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst new file mode 100644 index 000000000000..83a6fba2938e --- /dev/null +++ b/doc/devel/contributing.rst @@ -0,0 +1,414 @@ +.. _contributing: + +============ +Contributing +============ + +This project is a community effort, and everyone is welcome to +contribute. + +The project is hosted on https://github.com/matplotlib/matplotlib + +Submitting a bug report +======================= + +If you find a bug in the code or documentation, do not hesitate to submit a +ticket to the +`Bug Tracker `_. You are +also welcome to post feature requests or pull requests. + + +Retrieving and installing the latest version of the code +======================================================== + + +We use `Git `_ for version control and +`GitHub `_ for hosting our main repository. + +You can check out the latest sources with the command:: + + git clone git@github.com:matplotlib/matplotlib.git + + +After obtaining a local copy of the matplotlib source code (:ref:`set-up-fork`), +navigate to the matplotlib directory and run the following in the shell:: + + python setup.py develop + +or:: + + pip install -v -e . + + +This installs matplotlib for development (i.e., builds everything and places the +symbolic links back to the source code). + +.. warning:: + + If you already have a version of matplotlib installed, you will need to + uninstall it. + + +.. note:: + + If you decide to do install with ``python setup.py develop`` or ``pip + install -v -e``, you will have to rerun:: + + python setup.py build + + every time the source code of a compiled extension is changed (for + instance when switching branches or pulling changes from upstream). + + + +You can then run the tests to check your work environment is set up properly:: + + python tests.py + + +.. _nose: https://nose.readthedocs.io/en/latest/ +.. _pep8: https://pep8.readthedocs.io/en/latest/ + +.. note:: + + **Additional dependencies for testing**: nose_ (version 1.0 or later), `mock + `_ (if python < 3.3), `Ghostscript + `_, `Inkscape `_ + +.. note:: To make sure the tests run locally: + + * Copy setup.cfg.template to setup.cfg + * Edit setup.cfg to set ``test`` to True, and ``local_freetype`` to True + * If you have built matplotlib previously, remove the ``build`` folder. + * Execute the build command. + +When working on bleeding edge packages, setting up a +`virtual environment +`_ or a `conda +environment `_ is recommended. + +.. seealso:: + + * :ref:`testing` + + +Contributing code +================= + +How to contribute +----------------- + +The preferred way to contribute to matplotlib is to fork the `main +repository `__ on GitHub, +then submit a "pull request" (PR): + + 1. `Create an account `_ on + GitHub if you do not already have one. + + 2. Fork the `project repository + `__: click on the 'Fork' button + near the top of the page. This creates a copy of the code under your + account on the GitHub server. + + 3. Clone this copy to your local disk:: + + $ git clone git@github.com:YourLogin/matplotlib.git + + 4. Create a branch to hold your changes:: + + $ git checkout -b my-feature origin/master + + and start making changes. Never work in the ``master`` branch! + + 5. Work on this copy, on your computer, using Git to do the version + control. When you're done editing e.g., ``lib/matplotlib/collections.py``, + do:: + + $ git add lib/matplotlib/collections.py + $ git commit + + to record your changes in Git, then push them to GitHub with:: + + $ git push -u origin my-feature + +Finally, go to the web page of your fork of the matplotlib repo, +and click 'Pull request' to send your changes to the maintainers for review. +You may want to consider sending an email to the mailing list for more +visibility. + +.. seealso:: + + * `Git documentation `_ + * :ref:`development-workflow`. + * :ref:`using-git` + +Contributing pull requests +-------------------------- + +It is recommended to check that your contribution complies with the following +rules before submitting a pull request: + + * If your pull request addresses an issue, please use the title to describe + the issue and mention the issue number in the pull request description + to ensure a link is created to the original issue. + + * All public methods should have informative docstrings with sample + usage when appropriate. Use the + `numpy docstring standard `_ + + * Formatting should follow `PEP8 recommendation + `_. 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. + + * Each high-level plotting function should have a simple example in + 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. + + * Changes (both new features and bugfixes) should be tested. See + :ref:`testing` for more details. + + * Import the following modules using the standard scipy conventions:: + + import numpy as np + import numpy.ma as ma + import matplotlib as mpl + import matplotlib.pyplot as plt + import matplotlib.cbook as cbook + import matplotlib.patches as mpatches + + * If your change is a major new feature, add an entry to the ``What's new`` + section by adding a new file in ``doc/users/whats_new`` (see + :file:`doc/users/whats_new/README` for more information). + + * If you change the API in a backward-incompatible way, please + document it in `doc/api/api_changes`, by adding a new file describing your + changes (see :file:`doc/api/api_changes/README` for more information) + + * See below for additional points about + :ref:`keyword-argument-processing`, if code in your pull request + does that. + +In addition, you can check for common programming errors with the following +tools: + + * Code with a good unittest coverage (at least 70%, better 100%), check + with:: + + pip install coverage + python tests.py --with-coverage + + * No pyflakes warnings, check with:: + + pip install pyflakes + pyflakes path/to/module.py + +.. note:: + + The current state of the matplotlib code base is not compliant with all + of those guidelines, but we expect that enforcing those constraints on all + new contributions will move the overall code base quality in the right + direction. + + +.. seealso:: + + * :ref:`coding_guidelines` + * :ref:`testing` + * :ref:`documenting-matplotlib` + + + +.. _new_contributors: + +Issues for New Contributors +--------------------------- + +New contributors should look for the following tags when looking for issues. +We strongly recommend that new contributors tackle +`new-contributor-friendly `_ +issues (easy, well documented issues, that do not require an understanding of +the different submodules of matplotlib) and +`Easy-fix `_ +issues. This helps the contributor become familiar with the contribution +workflow, and for the core devs to become acquainted with the contributor; +besides which, we frequently underestimate how easy an issue is to solve! + +.. _other_ways_to_contribute: + +Other ways to contribute +========================= + + +Code is not the only way to contribute to matplotlib. For instance, +documentation is also a very important part of the project and often doesn't +get as much attention as it deserves. If you find a typo in the documentation, +or have made improvements, do not hesitate to send an email to the mailing +list or submit a GitHub pull request. Full documentation can be found under +the doc/ directory. + +It also helps us if you spread the word: reference the project from your blog +and articles or link to it from your website! + +.. _coding_guidelines: + +Coding guidelines +================= + +New modules and files: installation +----------------------------------- + +* If you have added new files or directories, or reorganized existing + ones, make sure the new files are included in the match patterns in + :file:`MANIFEST.in`, and/or in `package_data` in `setup.py`. + +C/C++ extensions +---------------- + +* Extensions may be written in C or C++. + +* Code style should conform to PEP7 (understanding that PEP7 doesn't + address C++, but most of its admonitions still apply). + +* Python/C interface code should be kept separate from the core C/C++ + code. The interface code should be named `FOO_wrap.cpp` or + `FOO_wrapper.cpp`. + +* Header file documentation (aka docstrings) should be in Numpydoc + format. We don't plan on using automated tools for these + docstrings, and the Numpydoc format is well understood in the + scientific Python community. + +.. _keyword-argument-processing: + +Keyword argument processing +--------------------------- + +Matplotlib makes extensive use of ``**kwargs`` for pass-through +customizations from one function to another. A typical example is in +:func:`matplotlib.pyplot.text`. The definition of the pylab text +function is a simple pass-through to +:meth:`matplotlib.axes.Axes.text`:: + + # in pylab.py + def text(*args, **kwargs): + ret = gca().text(*args, **kwargs) + draw_if_interactive() + return ret + +:meth:`~matplotlib.axes.Axes.text` in simplified form looks like this, +i.e., it just passes all ``args`` and ``kwargs`` on to +:meth:`matplotlib.text.Text.__init__`:: + + # in axes/_axes.py + def text(self, x, y, s, fontdict=None, withdash=False, **kwargs): + t = Text(x=x, y=y, text=s, **kwargs) + +and :meth:`~matplotlib.text.Text.__init__` (again with liberties for +illustration) just passes them on to the +:meth:`matplotlib.artist.Artist.update` method:: + + # in text.py + def __init__(self, x=0, y=0, text='', **kwargs): + Artist.__init__(self) + self.update(kwargs) + +``update`` does the work looking for methods named like +``set_property`` if ``property`` is a keyword argument. i.e., no one +looks at the keywords, they just get passed through the API to the +artist constructor which looks for suitably named methods and calls +them with the value. + +As a general rule, the use of ``**kwargs`` should be reserved for +pass-through keyword arguments, as in the example above. If all the +keyword args are to be used in the function, and not passed +on, use the key/value keyword args in the function definition rather +than the ``**kwargs`` idiom. + +In some cases, you may want to consume some keys in the local +function, and let others pass through. You can ``pop`` the ones to be +used locally and pass on the rest. For example, in +:meth:`~matplotlib.axes.Axes.plot`, ``scalex`` and ``scaley`` are +local arguments and the rest are passed on as +:meth:`~matplotlib.lines.Line2D` keyword arguments:: + + # in axes/_axes.py + def plot(self, *args, **kwargs): + scalex = kwargs.pop('scalex', True) + scaley = kwargs.pop('scaley', True) + if not self._hold: self.cla() + lines = [] + for line in self._get_lines(*args, **kwargs): + self.add_line(line) + lines.append(line) + +Note: there is a use case when ``kwargs`` are meant to be used locally +in the function (not passed on), but you still need the ``**kwargs`` +idiom. That is when you want to use ``*args`` to allow variable +numbers of non-keyword args. In this case, python will not allow you +to use named keyword args after the ``*args`` usage, so you will be +forced to use ``**kwargs``. An example is +:meth:`matplotlib.contour.ContourLabeler.clabel`:: + + # in contour.py + def clabel(self, *args, **kwargs): + fontsize = kwargs.get('fontsize', None) + inline = kwargs.get('inline', 1) + self.fmt = kwargs.get('fmt', '%1.3f') + colors = kwargs.get('colors', None) + if len(args) == 0: + levels = self.levels + indices = range(len(self.levels)) + elif len(args) == 1: + ...etc... + +.. _custom_backend: + +Developing a new backend +------------------------ + +If you are working on a custom backend, the *backend* setting in +:file:`matplotlibrc` (:ref:`customizing-matplotlib`) supports an +external backend via the ``module`` directive. if +:file:`my_backend.py` is a matplotlib backend in your +:envvar:`PYTHONPATH`, you can set it on one of several ways + +* in matplotlibrc:: + + backend : module://my_backend + + +* with the :envvar:`MPLBACKEND` environment variable:: + + > export MPLBACKEND="module://my_backend" + > python simple_plot.py + +* from the command shell with the `-d` flag:: + + > python simple_plot.py -dmodule://my_backend + +* with the use directive in your script:: + + import matplotlib + matplotlib.use('module://my_backend') + +.. _sample-data: + +Writing examples +---------------- + +We have hundreds of examples in subdirectories of +:file:`matplotlib/examples`, and these are automatically generated +when the website is built to show up both in the `examples +<../examples/index.html>`_ and `gallery +<../gallery.html>`_ sections of the website. + +Any sample data that the example uses should be kept small and +distributed with matplotlib in the +`lib/matplotlib/mpl-data/sample_data/` directory. Then in your +example code you can load it into a file handle with:: + + import matplotlib.cbook as cbook + fh = cbook.get_sample_data('mydata.dat') diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 0ac2823a6e16..85cb96039a58 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -1,8 +1,8 @@ .. _documenting-matplotlib: -********************** -Documenting matplotlib -********************** +=========================================== +Developer's tips for documenting matplotlib +=========================================== Getting started =============== diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index c37ec21b5edd..2399758c061a 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -1,8 +1,8 @@ .. _development-workflow: -==================== -Development workflow -==================== +========================= +Git Development workflow +========================= You've discovered a bug or something else you want to change in matplotlib_ .. |emdash| excellent! diff --git a/doc/devel/gitwash/matplotlib_for_dev.rst b/doc/devel/gitwash/matplotlib_for_dev.rst deleted file mode 100644 index f946eed3de0a..000000000000 --- a/doc/devel/gitwash/matplotlib_for_dev.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _matplotlib-for-dev: - -================================================= -Installing matplotlib from source for development -================================================= - -After obtaining a local copy of the matpotlib source code (:ref:`set-up-fork`), -navigate to the matplotlib directory and run the following in the shell: - -:: - - python setup.py develop - -or:: - - pip install -v -e . - -This installs matplotlib for development (i.e., builds everything and places -the symbolic links back to the source code). This command has to be called -everytime a `c` file is changed. Note that changing branches may change the -`c`-code. - -When working on bleeding edge packages, setting up a -`virtual environment -`_ or a `conda -environment `_ is recommended. - diff --git a/doc/devel/gitwash/setting_up_for_development.rst b/doc/devel/gitwash/setting_up_for_development.rst index 2182343a2e1b..d49122db6dab 100644 --- a/doc/devel/gitwash/setting_up_for_development.rst +++ b/doc/devel/gitwash/setting_up_for_development.rst @@ -11,7 +11,6 @@ Contents: forking_hell set_up_fork - matplotlib_for_dev configure_git development_workflow dot2_dot3 diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 71cac030bd8e..118f1f564db3 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -12,14 +12,18 @@ The Matplotlib Developers' Guide .. toctree:: :maxdepth: 2 - coding_guide.rst - portable_code.rst - license.rst - gitwash/index.rst + contributing.rst testing.rst documenting_mpl.rst - release_guide.rst - transformations.rst add_new_projection.rst - color_changes + portable_code.rst + gitwash/index.rst + coding_guide.rst + release_guide.rst MEP/index + +.. toctree:: + :hidden: + + license.rst + color_changes diff --git a/doc/devel/portable_code.rst b/doc/devel/portable_code.rst index a557905fa6dc..9274c181ac2b 100644 --- a/doc/devel/portable_code.rst +++ b/doc/devel/portable_code.rst @@ -1,5 +1,9 @@ -Writing code for Python 2 and 3 -------------------------------- + +.. _portable_code: + +===================================================== +Developer's tips for writing code for Python 2 and 3 +===================================================== As of matplotlib 1.4, the `six `_ library is used to support Python 2 and 3 from a single code base. diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index df7c8a74c475..fdf619ca853d 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -1,7 +1,8 @@ .. _testing: -Testing -======= +============================ +Developer's tips for testing +============================ Matplotlib has a testing infrastructure based on nose_, making it easy to write new tests. The tests are in :mod:`matplotlib.tests`, and @@ -9,7 +10,7 @@ customizations to the nose testing infrastructure are in :mod:`matplotlib.testing`. (There is other old testing cruft around, please ignore it while we consolidate our testing to these locations.) -.. _nose: http://nose.readthedocs.org/en/latest/ +.. _nose: https://nose.readthedocs.io/en/latest/ Requirements ------------ @@ -17,21 +18,17 @@ Requirements The following software is required to run the tests: - nose_, version 1.0 or later - - - `mock `_, when running python + - `mock `_, when running python versions < 3.3 - - - `Ghostscript `_ (to render PDF + - `Ghostscript `_ (to render PDF files) - - `Inkscape `_ (to render SVG files) Optionally you can install: - `coverage `_ to collect coverage information - - - `pep8 `_ to test coding standards + - `pep8 `_ to test coding standards Building matplotlib for image comparison tests ---------------------------------------------- @@ -106,7 +103,7 @@ matplotlib library function :func:`matplotlib.test`:: pip install mock -.. _`nosetest arguments`: http://nose.readthedocs.org/en/latest/usage.html +.. _`nosetest arguments`: http://nose.readthedocs.io/en/latest/usage.html Writing a simple test diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index e5ecdd514d46..05e03b73a2a5 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -205,7 +205,7 @@ Python.org Python ^^^^^^^^^^^^^^^^^ Install pip following the `standard pip install instructions -`_. For the impatient, +`_. For the impatient, open a new Terminal.app window and:: curl -O https://bootstrap.pypa.io/get-pip.py diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 094c3ca3432e..37a60668d136 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -53,7 +53,7 @@ to virtualenv when creating an environment. This adds all system wide packages to the virtual environment. However, this breaks the isolation between the virtual environment and the system install. Among other issues it results in hard to debug problems with system packages shadowing the environment packages. -If you use `virtualenvwrapper `_ +If you use `virtualenvwrapper `_ this can be toggled with the ``toggleglobalsitepackages`` command. Alternatively, you can manually symlink the GUI frameworks into the environment. diff --git a/doc/glossary/index.rst b/doc/glossary/index.rst index 5f0b683f14cf..468896d86977 100644 --- a/doc/glossary/index.rst +++ b/doc/glossary/index.rst @@ -16,7 +16,7 @@ Glossary dateutil - The `dateutil `_ library + The `dateutil `_ library provides extensions to the standard datetime module EPS diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index ba2db57a3e9f..3c0d5775264d 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2783,49 +2783,77 @@ def set_xbound(self, lower=None, upper=None): def get_xlim(self): """ - Get the x-axis range [*left*, *right*] + Get the x-axis range + + Returns + ------- + xlimits : tuple + Returns the current x-axis limits as the tuple + (`left`, `right`). + + Notes + ----- + The x-axis may be inverted, in which case the `left` value will + be greater than the `right` value. + """ return tuple(self.viewLim.intervalx) def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): """ - Set the data limits for the xaxis + Set the data limits for the x-axis - Examples:: + Parameters + ---------- + left : scalar, optional + The left xlim (default: None, which leaves the left limit + unchanged). The previous name `xmin` may be used instead. - set_xlim((left, right)) - set_xlim(left, right) - set_xlim(left=1) # right unchanged - set_xlim(right=1) # left unchanged + right : scalar, optional + The right xlim (default: None, which leaves the right limit + unchanged). The previous name `xmax` may be used instead. - Keyword arguments: + emit : bool, optional + Whether to notify observers of limit change (default: True). - *left*: scalar - The left xlim; *xmin*, the previous name, may still be used + auto : bool or None, optional + Whether to turn on autoscaling of the x-axis. True turns on, + False turns off (default action), None leaves unchanged. - *right*: scalar - The right xlim; *xmax*, the previous name, may still be used + xlimits : tuple, optional + The left and right xlims may be passed as the tuple + (`left`, `right`) as the first positional argument (or as + the `left` keyword argument). - *emit*: [ *True* | *False* ] - Notify observers of limit change + Returns + ------- + xlimits : tuple + Returns the current x-axis limits, reflecting any changes + made by this call, as (`left`, `right`). - *auto*: [ *True* | *False* | *None* ] - Turn *x* autoscaling on (*True*), off (*False*; default), - or leave unchanged (*None*) + Notes + ----- + The `left` value may be greater than the `right` value, in which + case the x-axis values will decrease from left to right. + + Examples + -------- + >>> set_xlim(left, right) + >>> set_xlim((left, right)) + >>> left, right = set_xlim(left, right) - Note, the *left* (formerly *xmin*) value may be greater than - the *right* (formerly *xmax*). - For example, suppose *x* is years before present. - Then one might use:: + One limit may be left unchanged. - set_xlim(5000, 0) + >>> set_xlim(right=right_lim) - so 5000 years ago is on the left of the plot and the + Limits may be passed in reverse order to flip the direction of + the x-axis. For example, suppose `x` represents the number of + years before present. The x-axis limits might be set like the + following so 5000 years ago is on the left of the plot and the present is on the right. - Returns the current xlimits as a length 2 tuple + >>> set_xlim(5000, 0) - ACCEPTS: length 2 sequence of floats """ if 'xmin' in kw: left = kw.pop('xmin') @@ -3037,49 +3065,78 @@ def set_ybound(self, lower=None, upper=None): def get_ylim(self): """ - Get the y-axis range [*bottom*, *top*] + Get the y-axis range + + Returns + ------- + ylimits : tuple + Returns the current y-axis limits as the tuple + (`bottom`, `top`). + + Notes + ----- + The y-axis may be inverted, in which case the `bottom` value + will be greater than the `top` value. + """ return tuple(self.viewLim.intervaly) def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw): """ - Set the data limits for the yaxis + Set the data limits for the y-axis - Examples:: + Parameters + ---------- + bottom : scalar, optional + The bottom ylim (default: None, which leaves the bottom + limit unchanged). The previous name `ymin` may be used + instead. - set_ylim((bottom, top)) - set_ylim(bottom, top) - set_ylim(bottom=1) # top unchanged - set_ylim(top=1) # bottom unchanged + top : scalar, optional + The top ylim (default: None, which leaves the top limit + unchanged). The previous name `ymax` may be used instead. - Keyword arguments: + emit : bool, optional + Whether to notify observers of limit change (default: True). - *bottom*: scalar - The bottom ylim; the previous name, *ymin*, may still be used + auto : bool or None, optional + Whether to turn on autoscaling of the y-axis. True turns on, + False turns off (default action), None leaves unchanged. - *top*: scalar - The top ylim; the previous name, *ymax*, may still be used + ylimits : tuple, optional + The bottom and top yxlims may be passed as the tuple + (`bottom`, `top`) as the first positional argument (or as + the `bottom` keyword argument). - *emit*: [ *True* | *False* ] - Notify observers of limit change + Returns + ------- + ylimits : tuple + Returns the current y-axis limits, reflecting any changes + made by this call, as (`bottom`, `top`). - *auto*: [ *True* | *False* | *None* ] - Turn *y* autoscaling on (*True*), off (*False*; default), - or leave unchanged (*None*) + Notes + ----- + The `bottom` value may be greater than the `top` value, in which + case the y-axis values will decrease from bottom to top. + + Examples + -------- + >>> set_ylim(bottom, top) + >>> set_ylim((bottom, top)) + >>> bottom, top = set_ylim(bottom, top) - Note, the *bottom* (formerly *ymin*) value may be greater than - the *top* (formerly *ymax*). - For example, suppose *y* is depth in the ocean. - Then one might use:: + One limit may be left unchanged. - set_ylim(5000, 0) + >>> set_ylim(top=top_lim) - so 5000 m depth is at the bottom of the plot and the - surface, 0 m, is at the top. + Limits may be passed in reverse order to flip the direction of + the y-axis. For example, suppose `y` represents depth of the + ocean in m. The y-axis limits might be set like the following + so 5000 m depth is at the bottom of the plot and the surface, + 0 m, is at the top. - Returns the current ylimits as a length 2 tuple + >>> set_ylim(5000, 0) - ACCEPTS: length 2 sequence of floats """ if 'ymin' in kw: bottom = kw.pop('ymin') diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 51f970ba3419..30805d67f6fe 100644 --- a/lib/matplotlib/dates.py +++ b/lib/matplotlib/dates.py @@ -39,7 +39,7 @@ locators you create. See `pytz `_ for information on :mod:`pytz` and timezone handling. -The `dateutil module `_ provides +The `dateutil module `_ provides additional code to handle date ticking, making it easy to place ticks on any kinds of dates. See examples below. @@ -87,7 +87,7 @@ :class:`matplotlib.dates.rrulewrapper`. The :class:`rrulewrapper` is a simple wrapper around a :class:`dateutil.rrule` (`dateutil - `_) which allow almost + `_) which allow almost arbitrary date tick specifications. See `rrule example <../examples/pylab_examples/date_demo_rrule.html>`_. diff --git a/matplotlibrc.template b/matplotlibrc.template index b628c52b355e..b6c3398df055 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -322,6 +322,12 @@ backend : $TEMPLATE_BACKEND # value of the data. +# axes.spines.left : True # display axis spines +# axes.spines.bottom : True +# axes.spines.top : True +# axes.spines.right : True + + #axes.unicode_minus : True # use unicode for the minus symbol # rather than hyphen. See # http://en.wikipedia.org/wiki/Plus_and_minus_signs#Character_codes