8000 DOC: reorganize and simplify contributing.rst by tacaswell · Pull Request #7699 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: reorganize and simplify contributing.rst #7699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 5, 2017
Merged

DOC: reorganize and simplify contributing.rst #7699

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fc5dcf4
DOC: reorganize and simplify contributing.rst
tacaswell Dec 29, 2016
600544c
DOC: ensure local variables are defined
tacaswell Dec 31, 2016
de50bfa
DOC: bit more accurate how develop mode works
tacaswell Dec 31, 2016
03111bf
DOC: standardize on Matplotlib
tacaswell Dec 31, 2016
534b832
DOC: minor tweaks to wording + capitalization
tacaswell Jan 5, 2017
39f8798
DOC: fix typo
tacaswell Jan 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 46 additions & 37 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,44 +21,65 @@ 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
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a
`conda environment <http://conda.pydata.org/docs/using/envs.html>`_ is
recommended.

.. warning::

If you already have a version of Matplotlib installed, use an
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.

We use `Git <https://git-scm.com/>`_ for version control and
`GitHub <https://github.com/>`_ 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 :file:`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 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

.. 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::
Expand All @@ -75,18 +96,6 @@ You can then run the tests to check your work environment is set up properly::
<https://docs.python.org/dev/library/unittest.mock.html>`_ (if python < 3.3), `Ghostscript
<https://www.ghostscript.com/>`_, `Inkscape <https://inkscape.org>`_

.. 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
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a `conda
environment <http://conda.pydata.org/docs/using/envs.html>`_ is recommended.

.. seealso::

* :ref:`testing`
Expand All @@ -98,7 +107,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 <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
then submit a "pull request" (PR):

Expand Down Expand Up @@ -131,7 +140,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.
Expand Down Expand Up @@ -207,7 +216,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.
Expand All @@ -230,7 +239,7 @@ New contributors should look for the following tags when looking for issues.
We strongly recommend that new contributors tackle
`new-contributor-friendly <https://github.com/matplotlib/matplotlib/labels/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 <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_
issues. This helps the contributor become familiar with the contribution
workflow, and for the core devs to become acquainted with the contributor;
Expand All @@ -242,7 +251,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
Expand Down Expand Up @@ -372,10 +381,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

Expand Down Expand Up @@ -406,7 +415,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::

Expand Down
14 changes: 6 additions & 8 deletions doc/users/tight_layout_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand Down Expand Up @@ -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',
)

Expand All @@ -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")

Expand All @@ -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")

Expand All @@ -318,7 +320,3 @@ explicitly create an axes for colorbar.
plt.colorbar(im, cax=cax)

plt.tight_layout()




0