8000 Merge pull request #7699 from tacaswell/doc_clearify_installation · matplotlib/matplotlib@3b4b781 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3b4b781

Browse files
QuLogicQuLogic
authored
Merge pull request #7699 from tacaswell/doc_clearify_installation
DOC: reorganize and simplify contributing.rst
2 parents 6c0ada0 + 39f8798 commit 3b4b781

File tree

2 files changed

+52
-45
lines changed

2 files changed

+52
-45
lines changed

‎doc/devel/contributing.rst

Lines changed: 46 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -21,44 +21,65 @@ also welcome to post feature requests or pull requests.
2121
Retrieving and installing the latest version of the code
2222
========================================================
2323

24+
When working on the Matplotlib source, setting up a `virtual
25+
environment
26+
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a
27+
`conda environment <http://conda.pydata.org/docs/using/envs.html>`_ is
28+
recommended.
29+
30+
.. warning::
31+
32+
If you already have a version of Matplotlib installed, use an
33+
virtual environment or uninstall using the same method you used
34+
to install it. Installing multiple versions of Matplotlib via different
35+
methods into the same environment may not always work as expected.
2436

2537
We use `Git <https://git-scm.com/>`_ for version control and
2638
`GitHub <https://github.com/>`_ for hosting our main repository.
2739

28-
You can check out the latest sources with the command::
40+
You can check out the latest sources with the command (see
41+
:ref:`set-up-fork` for more details)::
2942

3043
git clone git@github.com:matplotlib/matplotlib.git
3144

45+
and navigate to the :file:`matplotlib` directory.
3246

33-
After obtaining a local copy of the matplotlib source code (:ref:`set-up-fork`),
34-
navigate to the matplotlib directory and run the following in the shell::
47+
To make sure the tests run locally you must build against the correct version
48+
of freetype. To configure the build system to fetch and build it either export
49+
the env ``MPLLOCALFREETYPE`` as::
3550

36-
python setup.py develop
51+
export MPLLOCALFREETYPE=1
3752

38-
or::
53+
or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit to contain ::
3954

40-
pip install -v -e .
55+
[test]
56+
local_freetype = True
4157

4258

43-
This installs matplotlib for development (i.e., builds everything and places the
44-
symbolic links back to the source code).
59+
To install Matplotlib (and compile the c-extensions) run the following
60+
command from the top-level directory ::
4561

46-
.. warning::
62+
pip install -v -e ./
4763

48-
If you already have a version of matplotlib installed, you will need to
49-
uninstall it.
64+
This installs Matplotlib in 'editable/develop mode', i.e., builds
65+
everything and places the correct link entries in the install
66+
directory so that python will be able to import Matplotlib from the
67+
source directory. Thus, any changes to the ``*.py`` files will be
68+
reflected the next time you import the library. If you change the
69+
c-extension source (which might happen if you change branches) you
70+
will need to run::
5071

72+
python setup.py build
5173

52-
.. note::
74+
or re-run ``pip install -v -e ./``.
5375

54-
If you decide to do install with ``python setup.py develop`` or ``pip
55-
install -v -e``, you will have to rerun::
5676

57-
python setup.py build
77+
Alternatively, if you do ::
5878

59-
every time the source code of a compiled extension is changed (for
60-
instance when switching branches or pulling changes from upstream).
79+
pip install -v ./
6180

81+
all of the files will be copied to the installation directory however,
82+
you will have to rerun this command every time the source is changed.
6283

6384

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

78-
.. note:: To make sure the tests run locally:
79-
80-
* Copy setup.cfg.template to setup.cfg
81-
* Edit setup.cfg to set ``test`` to True, and ``local_freetype`` to True
82-
* If you have built matplotlib previously, remove the ``build`` folder.
83-
* Execute the build command.
84-
85-
When working on bleeding edge packages, setting up a
86-
`virtual environment
87-
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a `conda
88-
environment <http://conda.pydata.org/docs/using/envs.html>`_ is recommended.
89-
9099
.. seealso::
91100

92101
* :ref:`testing`
@@ -98,7 +107,7 @@ Contributing code
98107
How to contribute
99108
-----------------
100109

101-
The preferred way to contribute to matplotlib is to fork the `main
110+
The preferred way to contribute to Matplotlib is to fork the `main
102111
repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
103112
then submit a "pull request" (PR):
104113

@@ -131,7 +140,7 @@ then submit a "pull request" (PR):
131140

132141
$ git push -u origin my-feature
133142

134-
Finally, go to the web page of your fork of the matplotlib repo,
143+
Finally, go to the web page of your fork of the Matplotlib repo,
135144
and click 'Pull request' to send your changes to the maintainers for review.
136145
You may want to consider sending an email to the mailing list for more
137146
visibility.
@@ -207,7 +216,7 @@ tools:
207216

208217
.. note::
209218

210-
The current state of the matplotlib code base is not compliant with all
219+
The current state of the Matplotlib code base is not compliant with all
211220
of those guidelines, but we expect that enforcing those constraints on all
212221
new contributions will move the overall code base quality in the right
213222
direction.
@@ -230,7 +239,7 @@ New contributors should look for the following tags when looking for issues.
230239
We strongly recommend that new contributors tackle
231240
`new-contributor-friendly <https://github.com/matplotlib/matplotlib/labels/new-contributor-friendly>`_
232241
issues (easy, well documented issues, that do not require an understanding of
233-
the different submodules of matplotlib) and
242+
the different submodules of Matplotlib) and
234243
`Easy-fix <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_
235244
issues. This helps the contributor become familiar with the contribution
236245
workflow, and for the core devs to become acquainted with the contributor;
@@ -242,7 +251,7 @@ Other ways to contribute
242251
=========================
243252

244253

245-
Code is not the only way to contribute to matplotlib. For instance,
254+
Code is not the only way to contribute to Matplotlib. For instance,
246255
documentation is also a very important part of the project and often doesn't
247256
get as much attention as it deserves. If you find a typo in the documentation,
248257
or have made improvements, do not hesitate to send an email to the mailing
@@ -372,10 +381,10 @@ Developing a new backend
372381
If you are working on a custom backend, the *backend* setting in
373382
:file:`matplotlibrc` (:ref:`customizing-matplotlib`) supports an
374383
external backend via the ``module`` directive. if
375-
:file:`my_backend.py` is a matplotlib backend in your
384+
:file:`my_backend.py` is a Matplotlib backend in your
376385
:envvar:`PYTHONPATH`, you can set it on one of several ways
377386

378-
* in matplotlibrc::
387+
* in :file:`matplotlibrc`::
379388

380389
backend : module://my_backend
381390

@@ -406,7 +415,7 @@ when the website is built to show up both in the `examples
406415
<../gallery.html>`_ sections of the website.
407416

408417
Any sample data that the example uses should be kept small and
409-
distributed with matplotlib in the
418+
distributed with Matplotlib in the
410419
`lib/matplotlib/mpl-data/sample_data/` directory. Then in your
411420
example code you can load it into a file handle with::
412421

‎doc/users/tight_layout_guide.rst

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -211,13 +211,13 @@ For example, this can be used for a figure with multiple gridspecs.
211211
:context:
212212

213213
gs2 = gridspec.GridSpec(3, 1)
214-
214+
215215
for ss in gs2:
216216
ax = fig.add_subplot(ss)
217217
example_plot(ax)
218218
ax.set_title("")
219219
ax.set_xlabel("")
220-
220+
221221
ax.set_xlabel("x-label", fontsize=12)
222222

223223
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 ::
230230

231231
gs1.update(top=top, bottom=bottom)
232232
gs2.update(top=top, bottom=bottom)
233-
233+
234234

235235
While this should be mostly good enough, adjusting top and bottom
236236
may require adjustment of hspace also. To update hspace & vspace, we
@@ -269,7 +269,7 @@ While limited, the axes_grid1 toolkit is also supported.
269269
fig = plt.figure()
270270

271271
from mpl_toolkits.axes_grid1 import Grid
272-
grid = Grid(fig, rect=111, nrows_ncols=(2,2),
272+
grid = Grid(fig, rect=111, nrows_ncols=(2,2),
273273
axes_pad=0.25, label_mode='L',
274274
)
275275

@@ -294,6 +294,7 @@ colorbar as a subplot using the gridspec.
294294
:context:
295295

296296
plt.close('all')
297+
arr = np.arange(100).reshape((10,10))
297298
fig = plt.figure(figsize=(4, 4))
298299
im = plt.imshow(arr, interpolation="none")
299300

@@ -309,6 +310,7 @@ explicitly create an axes for colorbar.
309310
:context:
310311

311312
plt.close('all')
313+
arr = np.arange(100).reshape((10,10))
312314
fig = plt.figure(figsize=(4, 4))
313315
im = plt.imshow(arr, interpolation="none")
314316

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

320322
plt.tight_layout()
321-
322-
323-
324-

0 commit comments

Comments
 (0)
0