Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3338480

Browse files
committed
Merge branch 'docfix/improve_description' into v1.0.x
2 parents fb9a7e5 + f230d7a commit 3338480

File tree

10 files changed

+267
-112
lines changed

10 files changed

+267
-112
lines changed

doc/faq/howto_faq.rst

Lines changed: 81 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ Plotting: howto
1515

1616
.. _howto-findobj:
1717

18-
Find all objects in figure of a certain type
19-
-------------------------------------------------------------
18+
Find all objects in a figure of a certain type
19+
----------------------------------------------
2020

2121
Every matplotlib artist (see :ref:`artist-tutorial`) has a method
2222
called :meth:`~matplotlib.artist.Artist.findobj` that can be used to
@@ -27,16 +27,16 @@ following snippet finds every object in the figure which has a
2727
`set_color` property and makes the object blue::
2828

2929
def myfunc(x):
30-
return hasattr(x, 'set_color')
30+
return hasattr(x, 'set_color')
3131

3232
for o in fig.findobj(myfunc):
33-
o.set_color('blue')
33+
o.set_color('blue')
3434

3535
You can also filter on class instances::
3636

3737
import matplotlib.text as text
3838
for o in fig.findobj(text.Text):
39-
o.set_fontstyle('italic')
39+
o.set_fontstyle('italic')
4040

4141

4242
.. _howto-transparent:
@@ -70,7 +70,7 @@ on individual elements, eg::
7070

7171
.. _howto-multipage:
7272

73-
Save multiple plots in one pdf file
73+
Save multiple plots to one pdf file
7474
-----------------------------------
7575

7676
Many image file formats can only have one image per file, but some
@@ -87,7 +87,7 @@ the format::
8787

8888
savefig(pp, format='pdf')
8989

90-
A simpler way is to call
90+
An easier way is to call
9191
:meth:`PdfPages.savefig <matplotlib.backends.backend_pdf.PdfPages.savefig>`::
9292

9393
pp.savefig()
@@ -144,15 +144,14 @@ specify the location explicitly::
144144
ax = fig.add_axes([left, bottom, width, height])
145145

146146
where all values are in fractional (0 to 1) coordinates. See
147-
`axes_demo.py <http://matplotlib.sf.net/examples/axes_demo.py>`_ for
148-
an example of placing axes manually.
147+
:ref:`pylab_examples-axes_demo` for an example of placing axes manually.
149148

150149
.. _howto-auto-adjust:
151150

152151
Automatically make room for tick labels
153152
----------------------------------------------------
154153

155-
In most use cases, it is enough to simpy change the subplots adjust
154+
In most use cases, it is enough to simply change the subplots adjust
156155
parameters as described in :ref:`howto-subplots-adjust`. But in some
157156
cases, you don't know ahead of time what your tick labels will be, or
158157
how large they will be (data and labels outside your control may be
@@ -174,8 +173,8 @@ connecting
174173
get the window extent there, and then do something with it, eg move
175174
the left of the canvas over; see :ref:`event-handling-tutorial`.
176175

177-
Here is that gets a bounding box in relative figure coordinates (0..1)
178-
of each of the labels and uses it to move the left of the subplots
176+
Here is an example that gets a bounding box in relative figure coordinates
177+
(0..1) of each of the labels and uses it to move the left of the subplots
179178
over so that the tick labels fit in the figure
180179

181180
.. plot:: pyplots/auto_subplots_adjust.py
@@ -233,7 +232,7 @@ When plotting time series, eg financial time series, one often wants
233232
to leave out days on which there is no data, eg weekends. By passing
234233
in dates on the x-xaxis, you get large horizontal gaps on periods when
235234
there is not data. The solution is to pass in some proxy x-data, eg
236-
evenly sampled indicies, and then use a custom formatter to format
235+
evenly sampled indices, and then use a custom formatter to format
237236
these as dates. The example below shows how to use an 'index formatter'
238237
to achieve the desired plot::
239238

@@ -250,8 +249,8 @@ to achieve the desired plot::
250249
ind = np.arange(N) # the evenly spaced plot indices
251250

252251
def format_date(x, pos=None):
253-
thisind = np.clip(int(x+0.5), 0, N-1)
254-
return r.date[thisind].strftime('%Y-%m-%d')
252+
thisind = np.clip(int(x+0.5), 0, N-1)
253+
return r.date[thisind].strftime('%Y-%m-%d')
255254

256255
fig = plt.figure()
257256
ax = fig.add_subplot(111)
@@ -405,15 +404,15 @@ A frequent request is to have two scales for the left and right
405404
y-axis, which is possible using :func:`~matplotlib.pyplot.twinx` (more
406405
than two scales are not currently supported, though it is on the wish
407406
list). This works pretty well, though there are some quirks when you
408-
are trying to interactively pan and zoom, since both scales do not get
407+
are trying to interactively pan and zoom, because both scales do not get
409408
the signals.
410409

411-
The approach :func:`~matplotlib.pyplot.twinx` (and its sister
412-
:func:`~matplotlib.pyplot.twiny`) uses is to use *2 different axes*,
410+
The approach uses :func:`~matplotlib.pyplot.twinx` (and its sister
411+
:func:`~matplotlib.pyplot.twiny`) to use *2 different axes*,
413412
turning the axes rectangular frame off on the 2nd axes to keep it from
414413
obscuring the first, and manually setting the tick locs and labels as
415414
desired. You can use separate matplotlib.ticker formatters and
416-
locators as desired since the two axes are independent::
415+
locators as desired because the two axes are independent::
417416

418417
import numpy as np
419418
import matplotlib.pyplot as plt
@@ -444,7 +443,7 @@ Generate images without having a window popup
444443

445444
The easiest way to do this is use an image backend (see
446445
:ref:`what-is-a-backend`) such as Agg (for PNGs), PDF, SVG or PS. In
447-
your figure generating script, just place call
446+
your figure generating script, just call the
448447
:func:`matplotlib.use` directive before importing pylab or
449448
pyplot::
450449

@@ -465,17 +464,43 @@ pyplot::
465464
Use :func:`~matplotlib.pyplot.show`
466465
------------------------------------------
467466

468-
The user interface backends need to start the GUI mainloop, and this
469-
is what :func:`~matplotlib.pyplot.show` does. It tells matplotlib to
470-
raise all of the figure windows and start the mainloop. Because the
471-
mainloop is blocking, you should only call this once per script, at
472-
the end. If you are using matplotlib to generate images only and do
473-
not want a user interface window, you do not need to call ``show`` (see
474-
:ref:`howto-batch` and :ref:`what-is-a-backend`).
467+
When you want to view your plots on your display,
468+
the user interface backend will need to start the GUI mainloop.
469+
This is what :func:`~matplotlib.pyplot.show` does. It tells
470+
matplotlib to raise all of the figure windows created so far and start
471+
the mainloop. Because this mainloop is blocking (i.e., script execution is
472+
paused), you should only call this once per script, at the end. Script
473+
execution is resumed after the last window is closed. Therefore, if you are
474+
using matplotlib to generate only images and do not want a user interface
475+
window, you do not need to call ``show`` (see :ref:`howto-batch` and
476+
:ref:`what-is-a-backend`).
475477

478+
.. note::
479+
Because closing a figure window invokes the destruction of its plotting
480+
elements, you should call :func:`~matplotlib.pyplot.savefig` *before*
481+
calling ``show`` if you wish to save the figure as well as view it.
482+
483+
.. versionadded:: v1.0.0
484+
``show`` now starts the GUI mainloop only if it isn't already running.
485+
Therefore, multiple calls to ``show`` are now allowed.
476486

477-
Because it is expensive to draw, matplotlib does not want to redrawing the figure
478-
many times in a script such as the following::
487+
Having ``show`` block further execution of the script or the python
488+
interperator depends on whether matplotlib is set for interactive mode
489+
or not. In non-interactive mode (the default setting), execution is paused
490+
until the last figure window is closed. In interactive mode, the execution
491+
is not paused, which allows you to create additional figures (but the script
492+
won't finish until the last figure window is closed).
493+
494+
.. note::
495+
Support for interactive/non-interactive mode depends upon the backend.
496+
Until version 1.0.0 (and subsequent fixes for 1.0.1), the behavior of
497+
the interactive mode was not consistent across backends.
498+
As of v1.0.1, only the macosx backend differs from other backends
499+
because it does not support non-interactive mode.
500+
501+
502+
Because it is expensive to draw, you typically will not want matplotlib
503+
to redraw a figure many times in a script such as the following::
479504

480505
plot([1,2,3]) # draw here ?
481506
xlabel('time') # and here ?
@@ -484,24 +509,24 @@ many times in a script such as the following::
484509
show()
485510

486511

487-
It is *possible* to force matplotlib to draw after every command,
488-
which is what you usually want when working interactively at the
512+
However, it is *possible* to force matplotlib to draw after every command,
513+
which might be what you want when working interactively at the
489514
python console (see :ref:`mpl-shell`), but in a script you want to
490-
defer all drawing until the script has executed. This is especially
515+
defer all drawing until the call to ``show``. This is especially
491516
important for complex figures that take some time to draw.
492517
:func:`~matplotlib.pyplot.show` is designed to tell matplotlib that
493518
you're all done issuing commands and you want to draw the figure now.
494519

495520
.. note::
496521

497-
:func:`~matplotlib.pyplot.show` should be called at most once per
498-
script and it should be the last line of your script. At that
499-
point, the GUI takes control of the interpreter. If you want to
500-
force a figure draw, use :func:`~matplotlib.pyplot.draw` instead.
522+
:func:`~matplotlib.pyplot.show` should typically only be called
523+
at most once per script and it should be the last line of your script.
524+
At that point, the GUI takes control of the interpreter. If you want
525+
to force a figure draw, use :func:`~matplotlib.pyplot.draw` instead.
501526

502-
Many users are frustrated by show because they want it to be a
503-
blocking call that raises the figure, pauses the script until the
504-
figure is closed, and then allows the script to continue running until
527+
Many users are frustrated by ``show`` because they want it to be a
528+
blocking call that raises the figure, pauses the script until they
529+
close the figure, and then allow the script to continue running until
505530
the next figure is created and the next show is made. Something like
506531
this::
507532

@@ -512,7 +537,13 @@ this::
512537

513538
This is not what show does and unfortunately, because doing blocking
514539
calls across user interfaces can be tricky, is currently unsupported,
515-
though we have made some progress towards supporting blocking events.
540+
though we have made significant progress towards supporting blocking events.
541+
542+
.. versionadded:: v1.0.0
543+
As noted earlier, this restriction has been relaxed to allow multiple
544+
calls to ``show``. In *most* backends, you can now expect to be
545+
able to create new figures and raise them in a subsequent call to
546+
``show`` after closing the figures from a previous call to ``show``.
516547

517548

518549
.. _howto-contribute:
@@ -537,7 +568,7 @@ want to receive them in a standard format. If possible, for any
537568
non-trivial change, please include a complete, free-standing example
538569
that the developers can run unmodified which shows the undesired
539570
behavior pre-patch and the desired behavior post-patch, with a clear
540-
verbal description of what to look for. The original developer may
571+
verbal description of what to look for. A developer may
541572
have written the function you are working on years ago, and may no
542573
longer be with the project, so it is quite possible you are the world
543574
expert on the code you are patching and we want to hear as much detail
@@ -560,7 +591,7 @@ Contribute to matplotlib documentation
560591
-----------------------------------------
561592

562593
matplotlib is a big library, which is used in many ways, and the
563-
documentation we have only scratches the surface of everything it can
594+
documentation has only scratched the surface of everything it can
564595
do. So far, the place most people have learned all these features are
565596
through studying the examples (:ref:`how-to-search-examples`), which is a
566597
recommended and great way to learn, but it would be nice to have more
@@ -569,7 +600,7 @@ corners. This is where you come in.
569600

570601
There is a good chance you know more about matplotlib usage in some
571602
areas, the stuff you do every day, than many of the core developers
572-
who write most of the documentation. Just pulled your hair out
603+
who wrote most of the documentation. Just pulled your hair out
573604
compiling matplotlib for windows? Write a FAQ or a section for the
574605
:ref:`installing` page. Are you a digital signal processing wizard?
575606
Write a tutorial on the signal analysis plotting functions like
@@ -582,10 +613,10 @@ for it in the :ref:`users-guide-index`. Bundle matplotlib in a
582613

583614
matplotlib is documented using the `sphinx
584615
<http://sphinx.pocoo.org/index.html>`_ extensions to restructured text
585-
`ReST <http://docutils.sourceforge.net/rst.html>`_. sphinx is a
616+
`(ReST) <http://docutils.sourceforge.net/rst.html>`_. sphinx is an
586617
extensible python framework for documentation projects which generates
587618
HTML and PDF, and is pretty easy to write; you can see the source for this
588-
document or any page on this site by clicking on *Show Source* link
619+
document or any page on this site by clicking on the *Show Source* link
589620
at the end of the page in the sidebar (or `here
590621
<../_sources/faq/howto_faq.txt>`_ for this document).
591622

@@ -630,9 +661,9 @@ Agg is to call::
630661
For more on configuring your backend, see
631662
:ref:`what-is-a-backend`.
632663

633-
Alternatively, you can avoid pylab/pyplot altogeher, which will give
664+
Alternatively, you can avoid pylab/pyplot altogether, which will give
634665
you a little more control, by calling the API directly as shown in
635-
`agg_oo.py <http://matplotlib.sf.net/examples/api/agg_oo.py>`_ .
666+
:ref:`api_examples-agg_oo.py`.
636667

637668
You can either generate hardcopy on the filesystem by calling savefig::
638669

@@ -650,7 +681,9 @@ or by saving to a file handle::
650681
import sys
651682
fig.savefig(sys.stdout)
652683

653-
Here is an example using the Python Imaging Library PIL. First the figure is saved to a StringIO objectm which is then fed to PIL for further processing::
684+
Here is an example using the Python Imaging Library PIL. First the figure
685+
is saved to a StringIO object which is then fed to PIL for further
686+
processing::
654687

655688
import StringIO, Image
656689
imgdata = StringIO.StringIO()

doc/faq/installing_faq.rst

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ If you are still having trouble, see :ref:`reporting-problems`.
4444
.. _clean-install:
4545

4646
Cleanly rebuild and reinstall everything
47-
==================================================
47+
========================================
4848

4949
The steps depend on your platform and installation method.
5050

@@ -110,6 +110,17 @@ and build and install as usual with::
110110
> cd matplotlib
111111
> python setup.py install
112112

113+
.. note::
114+
115+
If you are on debian/ubuntu, you can get all the dependencies
116+
required to build matplotlib with::
117+
118+
sudo apt-get build-dep python-matplotlib
119+
120+
This does not build matplotlib, but it does get the install the
121+
build dependencies, which will make building from source easier.
122+
123+
113124
If you want to be able to follow the development branch as it changes just replace
114125
the last step with (Make sure you have **setuptools** installed)::
115126

@@ -151,15 +162,15 @@ generate postscript images from some numerical simulations, and still
151162
others in web application servers to dynamically serve up graphs.
152163

153164
To support all of these use cases, matplotlib can target different
154-
outputs, and each of these capabililities is called a backend; the
165+
outputs, and each of these capabilities is called a backend; the
155166
"frontend" is the user facing code, ie the plotting code, whereas the
156-
"backend" does all the dirty work behind the scenes to make the
167+
"backend" does all the hard work behind-the-scenes to make the
157168
figure. There are two types of backends: user interface backends (for
158169
use in pygtk, wxpython, tkinter, qt, macosx, or fltk) and hardcopy backends to
159170
make image files (PNG, SVG, PDF, PS).
160171

161172
There are a two primary ways to configure your backend. One is to set
162-
the ``backend`` parameter in you ``matplotlibrc`` file (see
173+
the ``backend`` parameter in your ``matplotlibrc`` file (see
163174
:ref:`customizing-matplotlib`)::
164175

165176
backend : WXAgg # use wxpython with antigrain (agg) rendering
@@ -172,8 +183,8 @@ The other is to use the matplotlib :func:`~matplotlib.use` directive::
172183
If you use the ``use`` directive, this must be done before importing
173184
:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
174185

175-
If you are unsure what to do, and just want to get cranking, just set
176-
your backend to ``TkAgg``. This will do the right thing for 95% of the
186+
If you are unsure what to do, and just want to get coding, just set
187+
your backend to ``TkAgg``. This will do the right thing for most
177188
users. It gives you the option of running your scripts in batch or
178189
working interactively from the python shell, with the least amount of
179190
hassles, and is smart enough to do the right thing when you ask for
@@ -198,7 +209,7 @@ For the rendering engines, one can also distinguish between `vector
198209
<http://en.wikipedia.org/wiki/Raster_graphics>`_ renderers. Vector
199210
graphics languages issue drawing commands like "draw a line from this
200211
point to this point" and hence are scale free, and raster backends
201-
generate a pixel represenation of the line whose accuracy depends on a
212+
generate a pixel representation of the line whose accuracy depends on a
202213
DPI setting.
203214

204215
Here is a summary of the matplotlib renderers (there is an eponymous
@@ -266,8 +277,8 @@ Compile matplotlib with PyGTK-2.4
266277
-------------------------------------------
267278

268279
There is a `bug in PyGTK-2.4`_. You need to edit
269-
:file:`pygobject.h` to add the :cmacro:`G_BEGIN_DECLS` and :cmacro:`G_END_DECLS`
270-
macros, and rename :cdata:`typename` parameter to :cdata:`typename_`::
280+
:file:`pygobject.h` to add the :c:macro:`G_BEGIN_DECLS` and :c:macro:`G_END_DECLS`
281+
macros, and rename :c:data:`typename` parameter to :c:data:`typename_`::
271282

272283
- const char *typename,
273284
+ const char *typename_,
@@ -312,9 +323,9 @@ mpkd directory, which will have a name like
312323
file:`matplotlib-0.99.0.rc1-py2.5-macosx10.5.mpkg`, it will run the
313324
Installer.app, prompt you for a password if you need system wide
314325
installation privileges, and install to a directory like
315-
file:`/Library/Python/2.5/site-packages/`, again depedending on your
326+
file:`/Library/Python/2.5/site-packages/`, again depending on your
316327
python version. This directory may not be in your python path, so you
317-
can test your installation with::
328+
should test your installation with::
318329

319330
> python -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
320331

@@ -335,7 +346,7 @@ See also ref:`environment-variables`.
335346
easy_install from egg
336347
------------------------------
337348

338-
You can also us the eggs we build for OSX (see the `installation
349+
You can also use the eggs we build for OSX (see the `installation
339350
instructions
340351
<http://pypi.python.org/pypi/setuptools#cygwin-mac-os-x-linux-other>`_
341352
for easy_install if you do not have it on your system already). You
@@ -368,7 +379,7 @@ matplotlib download site, with ``easy_install``, getting an error::
368379

369380
If you rename ``matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg`` to
370381
``matplotlib-0.98.0-py2.5.egg``, ``easy_install`` will install it from
371-
the disk. Many Mac OS X eggs with cruft at the end of the filename,
382+
the disk. Many Mac OS X eggs have cruft at the end of the filename,
372383
which prevents their installation through easy_install. Renaming is
373384
all it takes to install them; still, it's annoying.
374385

0 commit comments

Comments
 (0)