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 3 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
65 changes: 36 additions & 29 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,63 @@ 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, you will need to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Matplotlib

uninstall it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only in the same venv, I think? AFAICT that looks big and scary while it is simply not true if the instructions above are followed :-)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can drive your self to very strange situations with overlapping installs, but will re-word this to be a bit less scary.


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 matplotlib directory.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Matplotlib


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 +94,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 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 8000 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