From 6c601c0c9d3fd64f10977abbb1f129ee3d30911c Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Mon, 31 Oct 2016 20:23:40 -0400 Subject: [PATCH 01/18] Convert docstring for set_xlim(), per issue #7205 Convert set_xlim() docstring to numpydoc format. --- lib/matplotlib/axes/_base.py | 65 ++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index ba2db57a3e9f..fde425ef6a7b 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2789,43 +2789,58 @@ def get_xlim(self): 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 : {True, False, 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. - 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:: + Examples + -------- + >>> set_xlim(left, right) + >>> set_xlim((left, right)) + >>> left, right = set_xlim(left, right) - set_xlim(5000, 0) + One limit may be left unchanged. - so 5000 years ago is on the left of the plot and the - present is on the right. + >>> set_xlim(right=right_lim) - Returns the current xlimits as a length 2 tuple + Limits may be passed in reverse order. 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. + + >>> set_xlim(5000, 0) - ACCEPTS: length 2 sequence of floats """ if 'xmin' in kw: left = kw.pop('xmin') From 6ef07e760cc2c9e9711826c7efe3920c00896571 Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Mon, 31 Oct 2016 23:25:13 -0400 Subject: [PATCH 02/18] Convert set_xlim and set_ylim docstrings; #7205 Docstrings converted to numpydoc format. --- lib/matplotlib/axes/_base.py | 78 ++++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index fde425ef6a7b..cc0106951a18 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2804,7 +2804,7 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): emit : bool, optional Whether to notify observers of limit change (default: True). - auto : {True, False, None}, optional + 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. @@ -2834,10 +2834,11 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): >>> set_xlim(right=right_lim) - Limits may be passed in reverse order. 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. + 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. >>> set_xlim(5000, 0) @@ -3058,43 +3059,60 @@ def get_ylim(self): 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. - 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:: + Examples + -------- + >>> set_ylim(bottom, top) + >>> set_ylim((bottom, top)) + >>> bottom, top = set_ylim(bottom, top) + + 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') From d1182f277725c83a754425aff8763b253629d53d Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 18:19:58 -0700 Subject: [PATCH 03/18] ENH contributing guidelines are now all in one place --- doc/devel/coding_guide.rst | 388 ------------------ doc/devel/contributing.rst | 331 +++++++++++++++ doc/devel/gitwash/matplotlib_for_dev.rst | 27 -- .../gitwash/setting_up_for_development.rst | 1 - doc/devel/index.rst | 3 +- doc/devel/reviewers_guide.rst | 112 +++++ 6 files changed, 445 insertions(+), 417 deletions(-) delete mode 100644 doc/devel/coding_guide.rst create mode 100644 doc/devel/contributing.rst delete mode 100644 doc/devel/gitwash/matplotlib_for_dev.rst create mode 100644 doc/devel/reviewers_guide.rst diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst deleted file mode 100644 index 04edfb919417..000000000000 --- a/doc/devel/coding_guide.rst +++ /dev/null @@ -1,388 +0,0 @@ -.. _coding-guide: - -************ -Coding guide -************ - -.. _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. - - - 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. - -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 - in the `examples` tree. - -* Build the docs and make sure all formatting warnings are addressed. - -* See :ref:`documenting-matplotlib` for our documentation style guide. - -* If your changes are non-trivial, please make an entry in the - :file:`CHANGELOG`. - -* If your change is a major new feature, add an entry to - :file:`doc/users/whats_new.rst`. - -* 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 -==================== - -* If you have a commit bit, then you are trusted to use it. Please - help review and merge PRs! - -* Two developers (those with commit rights) should review all pull - requests. If you are the first to review a PR please and approve of - the changes please edit the title to include ``'[MRG+1]'`` and use - the github `'approve review' - `__ - tool to mark it as such. If you are a subsequent reviewer and you - approve either merge (and backport if needed) or increment the - number in the title to ask for further review (and trigger the gh - 'approve review'). If you do the merge please removed the - ``'[MRG+N']`` prefix. - -* 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 - contributor, keeping a relatively clean history, and keeping a - history usable for bisecting. The only time we are really strict - about it is to eliminate binary files (ex multiple test image - re-generations) and to remove upstream merges. - -* Be patient with new contributors. - -* Do not let perfect be the enemy of the good, particularly for - documentation or example PRs. If you find yourself making many - small suggestions, either open a PR against the original branch or - merge the PR and then open a new PR against upstream. - - - -Backports -========= - - -When doing backports please include the branch you backported the -commit to along with the SHA in a comment on the original PR. - -Assuming we have ``matplotlib`` as a read-only remote to the -matplotlib/matplotlib repo and ``DANGER`` as a read/write remote to -the matplotlib/matplotlib repo, we do a backport from master to 2.x. -The ``TARGET_SHA`` is the hash of the merge commit you would like to -backport. This can be read off of the github PR page (in the UI with -the merge notification) or through the git CLI tools.:: - - git fetch matplotlib - git checkout v2.x - git merge --ff-only matplotlib/v2.x - git cherry-pick -m 1 TARGET_SHA - gitk # to look at it - # local tests? (use your judgment) - git push DANGER v2.x - # leave a comment on PR noting sha of the resulting commit - # 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..e696ce4336e7 --- /dev/null +++ b/doc/devel/contributing.rst @@ -0,0 +1,331 @@ +.. _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 +======================= + +In case you experience issues using this package, 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 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. + +.. note:: + + If you decide to do this, 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). + +.. 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 build 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. + + +For more information on using git and Github, see :ref:`using-git`. + +Contributing code +================= + +Here are some guidelines on how new code should be written: + + * Formatting should follow `PEP8 + `_. 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. + + * Every new feature should be documented. Use the + `numpy docstring standard `_ + in all your docstrings. + + * 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 + from matplotlib import pyplot as plt + import matplotlib.cbook as cbook + import matplotlib.collections as mcol + import matplotlib.patches as mpatches + + * If your changes are non-trivial, please make an entry in the + :file:`CHANGELOG`. + + * If your change is a major new feature, add an entry to + :file:`doc/users/whats_new.rst`. + + * If you change the API in a backward-incompatible way, please + document it in :file:`doc/api/api_changes.rst`. + + + * Adding a new pyplot function involves generating code. See + :ref:`new-pyplot-function` for more information. + + * See below for additional points about + :ref:`keyword-argument-processing`, if code in your pull request + does that. + +More on :ref:`coding_guidelines` + +.. _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, link to it from your website, or simply say "I use it": + +.. raw:: html + + + + +.. _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 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. + +.. _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... + +.. _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/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..7978c001b8ef 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -12,7 +12,8 @@ The Matplotlib Developers' Guide .. toctree:: :maxdepth: 2 - coding_guide.rst + contributing.rst + reviewers_guide.rst portable_code.rst license.rst gitwash/index.rst diff --git a/doc/devel/reviewers_guide.rst b/doc/devel/reviewers_guide.rst new file mode 100644 index 000000000000..1d2149cc62f8 --- /dev/null +++ b/doc/devel/reviewers_guide.rst @@ -0,0 +1,112 @@ +.. _reviewers-guide: + +******************** +Reviewers guideline +******************** + +.. _pull-request-checklist: + +Pull request checklist +====================== + +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. + +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. + +* 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. + +* Build the docs and make sure all formatting warnings are addressed. + +* See :ref:`documenting-matplotlib` for our documentation style guide. + +* If your changes are non-trivial, please make an entry in the + :file:`CHANGELOG`. + +* If your change is a major new feature, add an entry to + :file:`doc/users/whats_new.rst`. + +* If you change the API in a backward-incompatible way, please + document it in :file:`doc/api/api_changes.rst`. + +PR Review guidelines +==================== + +* If you have a commit bit, then you are trusted to use it. Please + help review and merge PRs! + +* Two developers (those with commit rights) should review all pull + requests. If you are the first to review a PR please and approve of + the changes please edit the title to include ``'[MRG+1]'`` and use + the github `'approve review' + `__ + tool to mark it as such. If you are a subsequent reviewer and you + approve either merge (and backport if needed) or increment the + number in the title to ask for further review (and trigger the gh + '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 + contributor, keeping a relatively clean history, and keeping a + history usable for bisecting. The only time we are really strict + about it is to eliminate binary files (ex multiple test image + re-generations) and to remove upstream merges. + +* Be patient with new contributors. + +* Do not let perfect be the enemy of the good, particularly for + documentation or example PRs. If you find yourself making many + small suggestions, either open a PR against the original branch or + merge the PR and then open a new PR against upstream. + + + +Backports +========= + + +When doing backports please include the branch you backported the +commit to along with the SHA in a comment on the original PR. + +Assuming we have ``matplotlib`` as a read-only remote to the +matplotlib/matplotlib repo and ``DANGER`` as a read/write remote to +the matplotlib/matplotlib repo, we do a backport from master to 2.x. +The ``TARGET_SHA`` is the hash of the merge commit you would like to +backport. This can be read off of the github PR page (in the UI with +the merge notification) or through the git CLI tools.:: + + git fetch matplotlib + git checkout v2.x + git merge --ff-only matplotlib/v2.x + git cherry-pick -m 1 TARGET_SHA + gitk # to look at it + # local tests? (use your judgment) + git push DANGER v2.x + # leave a comment on PR noting sha of the resulting commit + # from the cherry-pick + branch it was moved to + +These commands work on git 2.7.1. From 02282e169d629ecf764c3262bf532317974b04dd Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 19:14:22 -0700 Subject: [PATCH 04/18] ENH Improved contributing documentation closes #7234 --- doc/devel/contributing.rst | 103 +++++++++++++++++++++++++++++++------ doc/devel/testing.rst | 4 -- 2 files changed, 87 insertions(+), 20 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index e696ce4336e7..98f4c1404e16 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -41,10 +41,13 @@ 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. +This installs matplotlib for development (i.e., builds everything and places the +symbolic links back to the source code). You can then run the tests your work +environment is set up properly:: + + python tests.py + +You can read more about testing :ref:`testings: .. note:: @@ -75,7 +78,63 @@ For more information on using git and Github, see :ref:`using-git`. Contributing code ================= -Here are some guidelines on how new code should be written: +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 scikit-learnon 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 + + 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, do:: + + $ git add modified_files + $ 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 the 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. + +If any of the above seems like magic to you, then look up the +`Git documentation `_ and our +`Git development workflow `_. + +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 todescribe + 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 presented as doctests when appropriate. Use the + `numpy docstring standard `_ * Formatting should follow `PEP8 `_. You should consider @@ -83,10 +142,6 @@ Here are some guidelines on how new code should be written: test suite is checking PEP8 compliance, things go smoother if the code is mostly PEP8 compliant to begin with. - * Every new feature should be documented. Use the - `numpy docstring standard `_ - in all your docstrings. - * 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 @@ -122,6 +177,28 @@ Here are some guidelines on how new code should be written: :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 get the overall code base quality in the right + direction. + + More on :ref:`coding_guidelines` .. _other_ways_to_contribute: @@ -138,13 +215,7 @@ 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, link to it from your website, or simply say "I use it": - -.. raw:: html - - - +and articles or link to it from your website! .. _coding_guidelines: diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index df7c8a74c475..1089b267220c 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -17,20 +17,16 @@ Requirements The following software is required to run the tests: - nose_, version 1.0 or later - - `mock `_, when running python versions < 3.3 - - `Ghostscript `_ (to render PDF files) - - `Inkscape `_ (to render SVG files) Optionally you can install: - `coverage `_ to collect coverage information - - `pep8 `_ to test coding standards Building matplotlib for image comparison tests From 18a3dd37603e524c72639cda9fd13cf2c3ea13a2 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 19:20:02 -0700 Subject: [PATCH 05/18] DOC remove transformation.rst and hide license doc --- doc/devel/contributing.rst | 2 +- doc/devel/index.rst | 7 +++++-- doc/devel/transformations.rst | 20 -------------------- 3 files changed, 6 insertions(+), 23 deletions(-) delete mode 100644 doc/devel/transformations.rst diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 98f4c1404e16..6a5f80f36a64 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -47,7 +47,7 @@ environment is set up properly:: python tests.py -You can read more about testing :ref:`testings: +You can read more about testing :ref:`testing` .. note:: diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 7978c001b8ef..33d98bdc5d5a 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -15,12 +15,15 @@ The Matplotlib Developers' Guide contributing.rst reviewers_guide.rst portable_code.rst - license.rst gitwash/index.rst testing.rst documenting_mpl.rst release_guide.rst - transformations.rst add_new_projection.rst color_changes MEP/index + +.. toctree:: + :hidden: + + license.rst diff --git a/doc/devel/transformations.rst b/doc/devel/transformations.rst deleted file mode 100644 index 1164031094fb..000000000000 --- a/doc/devel/transformations.rst +++ /dev/null @@ -1,20 +0,0 @@ -============================== - Working with transformations -============================== - -.. inheritance-diagram:: matplotlib.transforms matplotlib.path - :parts: 1 - -:mod:`matplotlib.transforms` -============================= - -.. automodule:: matplotlib.transforms - :members: TransformNode, BboxBase, Bbox, TransformedBbox, Transform, - TransformWrapper, AffineBase, Affine2DBase, Affine2D, IdentityTransform, - BlendedGenericTransform, BlendedAffine2D, blended_transform_factory, - CompositeGenericTransform, CompositeAffine2D, - composite_transform_factory, BboxTransform, BboxTransformTo, - BboxTransformFrom, ScaledTranslation, TransformedPath, nonsingular, - interval_contains, interval_contains_open - :show-inheritance: - From d93b65e3dcb40bfe4d46dc043ff32ab0f09f4c73 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 20:30:59 -0700 Subject: [PATCH 06/18] FIX typo --- doc/devel/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 6a5f80f36a64..3b4f92f347e6 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -82,7 +82,7 @@ How to contribute ----------------- The preferred way to contribute to matplotlib is to fork the `main -repository `__ on GitHub, +repository `__ on GitHub, then submit a "pull request" (PR): 1. `Create an account `_ on @@ -120,7 +120,7 @@ visibility. If any of the above seems like magic to you, then look up the `Git documentation `_ and our -`Git development workflow `_. +:ref:`development-workflow`. Contributing pull requests -------------------------- From 8377f856e8cde1429f30981643cb9e354bfe1d53 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 22:45:26 -0700 Subject: [PATCH 07/18] DOC improved organization and titles --- doc/devel/add_new_projection.rst | 6 +++--- doc/devel/documenting_mpl.rst | 6 +++--- doc/devel/index.rst | 10 +++++----- doc/devel/portable_code.rst | 8 ++++++-- doc/devel/testing.rst | 5 +++-- 5 files changed, 20 insertions(+), 15 deletions(-) diff --git a/doc/devel/add_new_projection.rst b/doc/devel/add_new_projection.rst index b05e05f5fc9a..676f8e9375b3 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 transformation +======================================================== .. ::author Michael Droettboom 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/index.rst b/doc/devel/index.rst index 33d98bdc5d5a..dbab8f772906 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -13,17 +13,17 @@ The Matplotlib Developers' Guide :maxdepth: 2 contributing.rst - reviewers_guide.rst - portable_code.rst - gitwash/index.rst testing.rst documenting_mpl.rst - release_guide.rst add_new_projection.rst - color_changes + portable_code.rst + gitwash/index.rst + reviewers_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..8ae905be3cba 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 1089b267220c..655973cc32c2 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 From 85034350b0a7e5e70c9d19584002f27933c29e0f Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Mon, 10 Oct 2016 17:44:59 -0700 Subject: [PATCH 08/18] ENH better styling for notes, warnings and see also section --- doc/_static/mpl.css | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index a9a7089f239c..3bf1f22a2ad7 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,31 @@ 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.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; } From 922dea4fc5e6bb77719aa0479b6c66154e343997 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Mon, 10 Oct 2016 18:11:40 -0700 Subject: [PATCH 09/18] DOC Better crosslinking of dev references --- doc/devel/contributing.rst | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 3b4f92f347e6..fa448b145fef 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -47,7 +47,11 @@ environment is set up properly:: python tests.py -You can read more about testing :ref:`testing` + +You may want to consider setting up a `virtual environment +`_ or a `conda +environment `_ + .. note:: @@ -58,22 +62,33 @@ You can read more about testing :ref:`testing` every time the source code of a compiled extension is changed (for instance when switching branches or pulling changes from upstream). +.. _nose: http://nose.readthedocs.org/en/latest/ +.. _pep8: http://pep8.readthedocs.org/en/latest/ + .. note:: - To make sure the tests run locally: + **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 build matplotlib previously, remove the build folder. * Execute the build command. - +<<<<<<< 8301de2110774994b720461335e5923998d80c99 When working on bleeding edge packages, setting up a `virtual environment `_ or a `conda environment `_ is recommended. +.. seealso:: + + * :ref:`testing` + * :ref:`using-git` -For more information on using git and Github, see :ref:`using-git`. Contributing code ================= @@ -118,9 +133,10 @@ 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. -If any of the above seems like magic to you, then look up the -`Git documentation `_ and our -:ref:`development-workflow`. +.. seealso:: + + * `Git documentation `_ + * :ref:`development-workflow`. Contributing pull requests -------------------------- @@ -136,7 +152,7 @@ rules before submitting a pull request: usage presented as doctests when appropriate. Use the `numpy docstring standard `_ - * Formatting should follow `PEP8 + * Formatting should follow `PEP8 recommandation `_. 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 @@ -199,7 +215,11 @@ tools: direction. -More on :ref:`coding_guidelines` +.. seealso:: + + * :ref:`coding_guidelines` + * :ref:`testing` + * :ref:`documenting-matplotlib` .. _other_ways_to_contribute: From 19067f05b5d1f05d5000db10c123d3147601cbf4 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Mon, 10 Oct 2016 18:33:05 -0700 Subject: [PATCH 10/18] DOC better title --- doc/devel/contributing.rst | 11 +++++------ doc/devel/gitwash/development_workflow.rst | 6 +++--- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index fa448b145fef..b8afc36268ee 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -67,10 +67,9 @@ environment `_ .. note:: - **Additional dependencies for testing**: nose_ (version 1.0 or later), - `mock `_ (if python < 3.3), - `Ghostscript `_, `Inkscape - `_ + **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: @@ -87,7 +86,6 @@ environment `_ is recommended. .. seealso:: * :ref:`testing` - * :ref:`using-git` Contributing code @@ -106,7 +104,7 @@ then submit a "pull request" (PR): 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 scikit-learnon the GitHub server. + account on the GitHub server. 3. Clone this copy to your local disk:: @@ -137,6 +135,7 @@ visibility. * `Git documentation `_ * :ref:`development-workflow`. + * :ref:`using-git` Contributing pull requests -------------------------- 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! From 7fb64b5eed4e1d16d4cb87cc605b29fbe0b2e5c6 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 11 Oct 2016 20:59:51 -0700 Subject: [PATCH 11/18] DOC no more addition to pyplot --- doc/devel/contributing.rst | 35 +++++------------------------------ 1 file changed, 5 insertions(+), 30 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index b8afc36268ee..37a5e14b446b 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -175,18 +175,13 @@ rules before submitting a pull request: import matplotlib.collections as mcol import matplotlib.patches as mpatches - * If your changes are non-trivial, please make an entry in the - :file:`CHANGELOG`. - - * If your change is a major new feature, add an entry to - :file:`doc/users/whats_new.rst`. + * If your change is a major new feature, add an entry to `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 :file:`doc/api/api_changes.rst`. - - - * Adding a new pyplot function involves generating code. See - :ref:`new-pyplot-function` for more information. + 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 @@ -399,23 +394,3 @@ 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. From d22af8f6c58bf8cdff330840830f50f250522ea5 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 11 Oct 2016 21:02:43 -0700 Subject: [PATCH 12/18] DOC fixes to the reviewer's guide --- doc/devel/{reviewers_guide.rst => coding_guide.rst} | 7 +++---- doc/devel/index.rst | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) rename doc/devel/{reviewers_guide.rst => coding_guide.rst} (95%) diff --git a/doc/devel/reviewers_guide.rst b/doc/devel/coding_guide.rst similarity index 95% rename from doc/devel/reviewers_guide.rst rename to doc/devel/coding_guide.rst index 1d2149cc62f8..8ff8508e0621 100644 --- a/doc/devel/reviewers_guide.rst +++ b/doc/devel/coding_guide.rst @@ -15,11 +15,10 @@ 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. + master. The rules are fuzzy here -- when in doubt, target master. - * Once changes are merged into the maintenance branch, they should - be merged into master. +* Once changes are merged into the maintenance branch, they should + be merged into master. Documentation ------------- diff --git a/doc/devel/index.rst b/doc/devel/index.rst index dbab8f772906..118f1f564db3 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -18,7 +18,7 @@ The Matplotlib Developers' Guide add_new_projection.rst portable_code.rst gitwash/index.rst - reviewers_guide.rst + coding_guide.rst release_guide.rst MEP/index From 88bfec12822169c9743cbf07f645f4cdc96f7797 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 11 Oct 2016 21:23:54 -0700 Subject: [PATCH 13/18] DOC added easy-fix and new-contributor-friendly tags --- doc/_static/mpl.css | 7 ++++++- doc/devel/contributing.rst | 28 +++++++++++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 3bf1f22a2ad7..7fcef5e061fc 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -400,11 +400,16 @@ div.admonition { } -div.note { +div.note, div.topic { background-color: #eee; border: 1px solid #ccc; } +p.topic-title { + font-size: 1.1em; + font-weight: bold; +} + div.seealso { background-color: #FFFBE8; border: 1px solid #fbeed5; diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 37a5e14b446b..7032bd37750c 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -77,7 +77,7 @@ environment `_ * Edit setup.cfg to set `test` to True, and `local_freetype` to True * If you have build matplotlib previously, remove the build folder. * Execute the build command. -<<<<<<< 8301de2110774994b720461335e5923998d80c99 + When working on bleeding edge packages, setting up a `virtual environment `_ or a `conda @@ -215,6 +215,32 @@ tools: * :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! + +.. topic:: new-contributor-friendly + + A great way to start contributing to matplotlib is to pick an item from + the list of + `new-contributor-friendly `_ + in the issue tracker. Resolving these issues allow you to start + contributing to the project without much prior knowledge. Your assistance + in this area will be greatly appreciated by the more experienced + developers as it helps free up their time to concentrate on other issues. + + .. _other_ways_to_contribute: Other ways to contribute From cabf7c0b95d6a240515addbf0a618ad9b4fcb6ef Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 11 Oct 2016 21:35:11 -0700 Subject: [PATCH 14/18] DOC better styling for topic sections * DOC adressed reviewer's comments * DOC rdt.org -> rdt.io --- doc/_static/mpl.css | 11 +++- doc/devel/add_new_projection.rst | 6 +- doc/devel/contributing.rst | 108 ++++++++++++++----------------- doc/devel/portable_code.rst | 2 +- doc/devel/testing.rst | 10 +-- doc/faq/installing_faq.rst | 2 +- doc/faq/virtualenv_faq.rst | 2 +- doc/glossary/index.rst | 2 +- lib/matplotlib/dates.py | 4 +- 9 files changed, 74 insertions(+), 73 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 7fcef5e061fc..0b5bce477ede 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -400,11 +400,20 @@ div.admonition { } -div.note, div.topic { +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; diff --git a/doc/devel/add_new_projection.rst b/doc/devel/add_new_projection.rst index 676f8e9375b3..9ef7c8f27ac0 100644 --- a/doc/devel/add_new_projection.rst +++ b/doc/devel/add_new_projection.rst @@ -1,8 +1,8 @@ .. _adding-new-scales: -======================================================== -Developer's guide for creating scales and transformation -======================================================== +========================================================= +Developer's guide for creating scales and transformations +========================================================= .. ::author Michael Droettboom diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 7032bd37750c..83a6fba2938e 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -12,7 +12,7 @@ The project is hosted on https://github.com/matplotlib/matplotlib Submitting a bug report ======================= -In case you experience issues using this package, do not hesitate to submit a +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. @@ -30,10 +30,8 @@ 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 matpotlib source code (:ref:`set-up-fork`), -navigate to the matplotlib directory and run the following in the shell: - -:: +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 @@ -41,41 +39,47 @@ or:: pip install -v -e . -This installs matplotlib for development (i.e., builds everything and places the -symbolic links back to the source code). You can then run the tests your work -environment is set up properly:: - python tests.py +This installs matplotlib for development (i.e., builds everything and places the +symbolic links back to the source code). +.. warning:: -You may want to consider setting up a `virtual environment -`_ or a `conda -environment `_ + If you already have a version of matplotlib installed, you will need to + uninstall it. .. note:: - If you decide to do this, you will have to rerun:: + 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). -.. _nose: http://nose.readthedocs.org/en/latest/ -.. _pep8: http://pep8.readthedocs.org/en/latest/ + + +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 `_ + `_ (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 build matplotlib previously, remove the build folder. + * 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 @@ -112,21 +116,22 @@ then submit a "pull request" (PR): 4. Create a branch to hold your changes:: - $ git checkout -b my-feature + $ 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, do:: + control. When you're done editing e.g., ``lib/matplotlib/collections.py``, + do:: - $ git add modified_files + $ 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 the your fork of the matplotlib repo, +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. @@ -143,24 +148,24 @@ 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 todescribe + * 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 presented as doctests when appropriate. Use the + usage when appropriate. Use the `numpy docstring standard `_ - * Formatting should follow `PEP8 recommandation - `_. You should consider + * 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 + 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. + in the ``examples`` tree. * Changes (both new features and bugfixes) should be tested. See :ref:`testing` for more details. @@ -170,13 +175,12 @@ rules before submitting a pull request: import numpy as np import numpy.ma as ma import matplotlib as mpl - from matplotlib import pyplot as plt + import matplotlib.pyplot as plt import matplotlib.cbook as cbook - import matplotlib.collections as mcol import matplotlib.patches as mpatches - * If your change is a major new feature, add an entry to `What's new` - section by adding a new file in `doc/users/whats_new` (see + * 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 @@ -205,7 +209,7 @@ tools: 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 get the overall code base quality in the right + new contributions will move the overall code base quality in the right direction. @@ -223,23 +227,14 @@ 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" +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! - -.. topic:: new-contributor-friendly - - A great way to start contributing to matplotlib is to pick an item from - the list of - `new-contributor-friendly `_ - in the issue tracker. Resolving these issues allow you to start - contributing to the project without much prior knowledge. Your assistance - in this area will be greatly appreciated by the more experienced - developers as it helps free up their time to concentrate on other issues. - +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: @@ -266,7 +261,7 @@ New modules and files: installation ----------------------------------- * If you have added new files or directories, or reorganized existing - ones, make sure the new files included in the match patterns in + 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 @@ -277,9 +272,6 @@ C/C++ extensions * 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`. @@ -296,7 +288,7 @@ 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 +:func:`matplotlib.pyplot.text`. The definition of the pylab text function is a simple pass-through to :meth:`matplotlib.axes.Axes.text`:: @@ -310,7 +302,7 @@ function is a simple pass-through to i.e., it just passes all ``args`` and ``kwargs`` on to :meth:`matplotlib.text.Text.__init__`:: - # in axes.py + # in axes/_axes.py def text(self, x, y, s, fontdict=None, withdash=False, **kwargs): t = Text(x=x, y=y, text=s, **kwargs) @@ -342,7 +334,7 @@ used locally and pass on the rest. For example, in local arguments and the rest are passed on as :meth:`~matplotlib.lines.Line2D` keyword arguments:: - # in axes.py + # in axes/_axes.py def plot(self, *args, **kwargs): scalex = kwargs.pop('scalex', True) scaley = kwargs.pop('scaley', True) @@ -381,7 +373,7 @@ 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 +:envvar:`PYTHONPATH`, you can set it on one of several ways * in matplotlibrc:: diff --git a/doc/devel/portable_code.rst b/doc/devel/portable_code.rst index 8ae905be3cba..9274c181ac2b 100644 --- a/doc/devel/portable_code.rst +++ b/doc/devel/portable_code.rst @@ -2,7 +2,7 @@ .. _portable_code: ===================================================== -Developer's tips for writing code for python 2 and 3 +Developer's tips for writing code for Python 2 and 3 ===================================================== As of matplotlib 1.4, the `six `_ diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 655973cc32c2..fdf619ca853d 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -10,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 ------------ @@ -18,9 +18,9 @@ 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) @@ -28,7 +28,7 @@ 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 ---------------------------------------------- @@ -103,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/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>`_. From 8b85f22291aeeed3d1e582b5b8f81531f539dd3a Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Sat, 29 Oct 2016 11:57:31 -0700 Subject: [PATCH 15/18] DOC Transformations are now documented in the API --- doc/api/index.rst | 1 + doc/api/transformations.rst | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 doc/api/transformations.rst 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/api/transformations.rst b/doc/api/transformations.rst new file mode 100644 index 000000000000..1164031094fb --- /dev/null +++ b/doc/api/transformations.rst @@ -0,0 +1,20 @@ +============================== + Working with transformations +============================== + +.. inheritance-diagram:: matplotlib.transforms matplotlib.path + :parts: 1 + +:mod:`matplotlib.transforms` +============================= + +.. automodule:: matplotlib.transforms + :members: TransformNode, BboxBase, Bbox, TransformedBbox, Transform, + TransformWrapper, AffineBase, Affine2DBase, Affine2D, IdentityTransform, + BlendedGenericTransform, BlendedAffine2D, blended_transform_factory, + CompositeGenericTransform, CompositeAffine2D, + composite_transform_factory, BboxTransform, BboxTransformTo, + BboxTransformFrom, ScaledTranslation, TransformedPath, nonsingular, + interval_contains, interval_contains_open + :show-inheritance: + From a55f55f2c19fdca3b26aac98666068a5f9e2937a Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 1 Nov 2016 15:16:51 +1100 Subject: [PATCH 16/18] Example of axes.spines.SIDE prop in matplotlibrc This addition is intended to prevent further questions about this on the mailing list: https://mail.python.org/pipermail/matplotlib-users/2016-October/000669.html --- matplotlibrc.template | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/matplotlibrc.template b/matplotlibrc.template index b628c52b355e..a09b776563f2 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -322,6 +322,12 @@ backend : $TEMPLATE_BACKEND # value of the data. +# axes.spines.left : True # Turn off the top and right axes spines +# axes.spines.bottom : True +# axes.spines.top : False +# axes.spines.right : False + + #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 From a9f0a8fff8903b746889d23ffbb29e7d463908ca Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Wed, 2 Nov 2016 08:25:52 +1100 Subject: [PATCH 17/18] Leave axis spines on by default, even in comments --- matplotlibrc.template | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/matplotlibrc.template b/matplotlibrc.template index a09b776563f2..b6c3398df055 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -322,10 +322,10 @@ backend : $TEMPLATE_BACKEND # value of the data. -# axes.spines.left : True # Turn off the top and right axes spines +# axes.spines.left : True # display axis spines # axes.spines.bottom : True -# axes.spines.top : False -# axes.spines.right : False +# axes.spines.top : True +# axes.spines.right : True #axes.unicode_minus : True # use unicode for the minus symbol From 6c5a44ec10baed57c40128c5a265ae774c22f51a Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Wed, 2 Nov 2016 23:26:44 -0400 Subject: [PATCH 18/18] Convert get_xlim and get_ylim docstrings --- lib/matplotlib/axes/_base.py | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index cc0106951a18..3c0d5775264d 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2783,7 +2783,19 @@ 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) @@ -3053,7 +3065,19 @@ 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)