From fc5dcf4827a13038e54d877dc2336dc672373f9c Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Wed, 28 Dec 2016 21:58:33 -0500 Subject: [PATCH 1/6] DOC: reorganize and simplify contributing.rst - only provide one installation direction - put details about local testing at the top --- doc/devel/contributing.rst | 64 +++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 025b2b199953..dfa12d3f9b17 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -21,44 +21,62 @@ also welcome to post feature requests or pull requests. Retrieving and installing the latest version of the code ======================================================== +When working on the Matplotlib source, setting up a `virtual +environment +`_ or a +`conda environment `_ is +recommended. + +.. warning:: + + If you already have a version of matplotlib installed, you will need to + uninstall it. We use `Git `_ for version control and `GitHub `_ for hosting our main repository. -You can check out the latest sources with the command:: +You can check out the latest sources with the command (see +:ref:`set-up-fork` for more details):: git clone git@github.com:matplotlib/matplotlib.git +and navigate to the matplotlib directory. -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:: +To make sure the tests run locally you must build against the correct version +of freetype. To configure the build system to fetch and build it either export +the env ``MPLLOCALFREETYPE`` as:: - python setup.py develop + export MPLLOCALFREETYPE=1 -or:: +or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit to contain :: - pip install -v -e . + [test] + local_freetype = True -This installs matplotlib for development (i.e., builds everything and places the -symbolic links back to the source code). +To install Matplotlib (and compile the c-extensions) run the following +command from the top-level directory :: -.. warning:: + pip install -v -e ./ - If you already have a version of matplotlib installed, you will need to - uninstall it. +This installs Matplotlib in 'editable/develop mode', i.e., +builds everything and places symbolic links back to the source code +from the install directory. Thus, any changes to the ``*.py`` files +will be reflected the next time you import the library. If you change +the c-extension source (which might happen if you change branches) you +will need to run:: + python setup.py build -.. note:: +or re-run ``pip install -v -e ./``. - 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 +Alternatively, if you do :: - every time the source code of a compiled extension is changed (for - instance when switching branches or pulling changes from upstream). + pip install -v ./ +all of the files will be copied to the installation directory however, +you will have to rerun this command every time the source is changed. You can then run the tests to check your work environment is set up properly:: @@ -75,18 +93,6 @@ You can then run the tests to check your work environment is set up properly:: `_ (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` From 600544c6371200573f43b01b58891926942852f0 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 31 Dec 2016 11:39:13 -0500 Subject: [PATCH 2/6] DOC: ensure local variables are defined --- doc/users/tight_layout_guide.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/doc/users/tight_layout_guide.rst b/doc/users/tight_layout_guide.rst index 4a28c3d2b9bc..7f008901a2a8 100644 --- a/doc/users/tight_layout_guide.rst +++ b/doc/users/tight_layout_guide.rst @@ -211,13 +211,13 @@ For example, this can be used for a figure with multiple gridspecs. :context: gs2 = gridspec.GridSpec(3, 1) - + for ss in gs2: ax = fig.add_subplot(ss) example_plot(ax) ax.set_title("") ax.set_xlabel("") - + ax.set_xlabel("x-label", fontsize=12) gs2.tight_layout(fig, rect=[0.5, 0, 1, 1], h_pad=0.5) @@ -230,7 +230,7 @@ We may try to match the top and bottom of two grids :: gs1.update(top=top, bottom=bottom) gs2.update(top=top, bottom=bottom) - + While this should be mostly good enough, adjusting top and bottom may require adjustment of hspace also. To update hspace & vspace, we @@ -269,7 +269,7 @@ While limited, the axes_grid1 toolkit is also supported. fig = plt.figure() from mpl_toolkits.axes_grid1 import Grid - grid = Grid(fig, rect=111, nrows_ncols=(2,2), + grid = Grid(fig, rect=111, nrows_ncols=(2,2), axes_pad=0.25, label_mode='L', ) @@ -294,6 +294,7 @@ colorbar as a subplot using the gridspec. :context: plt.close('all') + arr = np.arange(100).reshape((10,10)) fig = plt.figure(figsize=(4, 4)) im = plt.imshow(arr, interpolation="none") @@ -309,6 +310,7 @@ explicitly create an axes for colorbar. :context: plt.close('all') + arr = np.arange(100).reshape((10,10)) fig = plt.figure(figsize=(4, 4)) im = plt.imshow(arr, interpolation="none") @@ -318,7 +320,3 @@ explicitly create an axes for colorbar. plt.colorbar(im, cax=cax) plt.tight_layout() - - - - From de50bfa61524939b65ac351f30ecc6c1ce2bd6f5 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 31 Dec 2016 12:42:38 -0500 Subject: [PATCH 3/6] DOC: bit more accurate how develop mode works --- doc/devel/contributing.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index dfa12d3f9b17..4a08a3128840 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -59,11 +59,12 @@ command from the top-level directory :: pip install -v -e ./ -This installs Matplotlib in 'editable/develop mode', i.e., -builds everything and places symbolic links back to the source code -from the install directory. Thus, any changes to the ``*.py`` files -will be reflected the next time you import the library. If you change -the c-extension source (which might happen if you change branches) you +This installs Matplotlib in 'editable/develop mode', i.e., builds +everything and places the correct link entries in the install +directory so that python will be able to import Matplotlib from the +source directory. Thus, any changes to the ``*.py`` files will be +reflected the next time you import the library. If you change the +c-extension source (which might happen if you change branches) you will need to run:: python setup.py build From 03111bf5381812200efd16c9519372de77e50253 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 31 Dec 2016 15:23:18 -0500 Subject: [PATCH 4/6] DOC: standardize on Matplotlib --- doc/devel/contributing.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 4a08a3128840..147233e896b1 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -29,7 +29,7 @@ recommended. .. warning:: - If you already have a version of matplotlib installed, you will need to + If you already have a version of Matplotlib installed, you will need to uninstall it. We use `Git `_ for version control and @@ -40,7 +40,7 @@ You can check out the latest sources with the command (see git clone git@github.com:matplotlib/matplotlib.git -and navigate to the matplotlib directory. +and navigate to the Matplotlib directory. To make sure the tests run locally you must build against the correct version of freetype. To configure the build system to fetch and build it either export @@ -105,7 +105,7 @@ Contributing code How to contribute ----------------- -The preferred way to contribute to matplotlib is to fork the `main +The preferred way to contribute to Matplotlib is to fork the `main repository `__ on GitHub, then submit a "pull request" (PR): @@ -138,7 +138,7 @@ then submit a "pull request" (PR): $ git push -u origin my-feature -Finally, go to the web page of 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. @@ -214,7 +214,7 @@ tools: .. note:: - The current state of the matplotlib code base is not compliant with all + 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. @@ -237,7 +237,7 @@ 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 +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; @@ -249,7 +249,7 @@ Other ways to contribute ========================= -Code is not the only way to contribute to matplotlib. For instance, +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 @@ -379,10 +379,10 @@ 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 +:file:`my_backend.py` is a Matplotlib backend in your :envvar:`PYTHONPATH`, you can set it on one of several ways -* in matplotlibrc:: +* in :file:`matplotlibrc`:: backend : module://my_backend @@ -413,7 +413,7 @@ when the website is built to show up both in the `examples <../gallery.html>`_ sections of the website. Any sample data that the example uses should be kept small and -distributed with matplotlib in the +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:: From 534b832c467ff47d788bebec41593d5a3198e08c Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 5 Jan 2017 15:45:35 -0500 Subject: [PATCH 5/6] DOC: minor tweaks to wording + capitalization --- doc/devel/contributing.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 147233e896b1..66e43e0ca282 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -29,8 +29,10 @@ recommended. .. warning:: - If you already have a version of Matplotlib installed, you will need to - uninstall it. + If you already have a version of Matplotlib installed, use an + virtual environment or uninstalling using the same method you used + to install it. Installing multiple versions of Matplotlib via different + methods into the same environment may not always work as expected. We use `Git `_ for version control and `GitHub `_ for hosting our main repository. @@ -40,7 +42,7 @@ You can check out the latest sources with the command (see git clone git@github.com:matplotlib/matplotlib.git -and navigate to the Matplotlib directory. +and navigate to the :file:`matplotlib` directory. To make sure the tests run locally you must build against the correct version of freetype. To configure the build system to fetch and build it either export From 39f87987eedbe55567844d3f2ae18a2ac43805ee Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 5 Jan 2017 16:58:07 -0500 Subject: [PATCH 6/6] DOC: fix typo --- doc/devel/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 66e43e0ca282..8ddb927db44f 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -30,7 +30,7 @@ recommended. .. warning:: If you already have a version of Matplotlib installed, use an - virtual environment or uninstalling using the same method you used + virtual environment or uninstall using the same method you used to install it. Installing multiple versions of Matplotlib via different methods into the same environment may not always work as expected.