Revision: 6250
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6250&view=rev
Author: jdh2358
Date: 2008-10-17 18:51:10 +0000 (Fri, 17 Oct 2008)
Log Message:
-----------
reorg how to faq
Modified Paths:
--------------
trunk/matplotlib/doc/faq/howto_faq.rst
trunk/matplotlib/doc/make.py
Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 18:20:09 UTC (rev
6249)
+++ trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 18:51:10 UTC (rev
6250)
@@ -7,10 +7,15 @@
.. contents::
+.. _howto-plotting:
+
+Plotting: howto
+=================
+
.. _howto-findobj:
Find all objects in figure of a certain type
-=============================================================
+-------------------------------------------------------------
Every matplotlib artist (see :ref:`artist-tutorial`) has a method
called :meth:`~matplotlib.artist.Artist.findobj` that can be used to
@@ -36,7 +41,7 @@
.. _howto-transparent:
Save transparent figures
-==================================
+----------------------------------
The :meth:`~matplotlib.pyplot.savefig` command has a keyword argument
*transparent* which, if True, will make the figure and axes
@@ -65,7 +70,7 @@
.. _howto-subplots-adjust:
Move the edge of an axes to make room for tick labels
-============================================================================
+----------------------------------------------------------------------------
For subplots, you can control the default spacing on the left, right,
bottom, and top as well as the horizontal and vertical spacing between
@@ -115,7 +120,7 @@
.. _howto-auto-adjust:
Automatically make room for tick labels
-====================================================
+----------------------------------------------------
In most use cases, it is enough to simpy change the subplots adjust
parameters as described in :ref:`howto-subplots-adjust`. But in some
@@ -149,7 +154,7 @@
.. _howto-ticks:
Configure the tick linewidths
-=======================================
+---------------------------------------
In matplotlib, the ticks are *markers*. All
:class:`~matplotlib.lines.Line2D` objects support a line (solid,
@@ -175,7 +180,7 @@
.. _howto-align-label:
Align my ylabels across multiple subplots
-===================================================
+---------------------------------------------------
If you have multiple subplots over one another, and the y data have
different scales, you can often get ylabels that do not align
@@ -189,74 +194,10 @@
.. plot:: align_ylabels.py
:include-source:
-.. _howto-webapp:
-
-Matplotlib in a web application server
-====================================================
-
-Many users report initial problems trying to use maptlotlib in web
-application servers, because by default matplotlib ships configured to
-work with a graphical user interface which may require an X11
-connection. Since many barebones application servers do not have X11
-enabled, you may get errors if you don't configure matplotlib for use
-in these environments. Most importantly, you need to decide what
-kinds of images you want to generate (PNG, PDF, SVG) and configure the
-appropriate default backend. For 99% of users, this will be the Agg
-backend, which uses the C++ `antigrain <http://antigrain.com>`_
-rendering engine to make nice PNGs. The Agg backend is also
-configured to recognize requests to generate other output formats
-(PDF, PS, EPS, SVG). The easiest way to configure matplotlib to use
-Agg is to call::
-
- # do this before importing pylab or pyplot
- import matplotlib
- matplotlib.use('Agg')
- import matplotlib.pyplot as plt
-
-For more on configuring your backend, see
-:ref:`what-is-a-backend`.
-
-Alternatively, you can avoid pylab/pyplot altogeher, which will give
-you a little more control, by calling the API directly as shown in
-`agg_oo.py <http://matplotlib.sf.net/examples/api/agg_oo.py>`_ .
-
-You can either generate hardcopy on the filesystem by calling savefig::
-
- # do this before importing pylab or pyplot
- import matplotlib
- matplotlib.use('Agg')
- import matplotlib.pyplot as plt
- fig = plt.figure()
- ax = fig.add_subplot(111)
- ax.plot([1,2,3])
- fig.savefig('test.png')
-
-or by saving to a file handle::
-
- import sys
- fig.savefig(sys.stdout)
-
-
-matplotlib with apache
-------------------------------------
-
-TODO
-
-matplotlib with django
-------------------------------------
-
-TODO
-
-matplotlib with zope
-----------------------------------
-
-TODO
-
-
.. _date-index-plots:
Skip dates where there is no data
-===========================================
+-------------------------------------
When plotting time series, eg financial time series, one often wants
to leave out days on which there is no data, eg weekends. By passing
@@ -293,7 +234,7 @@
.. _point-in-poly:
Test whether a point is inside a polygon
-==================================================
+-------------------------------------------
The :mod:`matplotlib.nxutils` provides two high performance methods:
for a single point use :func:`~matplotlib.nxutils.pnpoly` and for an
@@ -337,123 +278,12 @@
For a complete example, see :ref:`event_handling-lasso_demo`.
-
-.. _how-to-submit-patch:
-
-Submit a patch
-========================
-
-First obtain a copy of matplotlib svn (see :ref:`install-svn`) and
-make your changes to the matplotlib source code or documentation and
-apply a `svn diff`. If it is feasible, do your diff from the top
-level directory, the one that contains :file:`setup.py`. Eg,::
-
- > cd /path/to/matplotlib/source
- > svn diff > mypatch.diff
-
-and then post your patch to the `matplotlib-devel
-<http://sourceforge.net/mail/?group_id=80706>`_ mailing list. If you
-do not get a response within 24 hours, post your patch to the
-sourceforge patch `tracker
-<http://sourceforge.net/tracker2/?atid=560722&group_id=80706&func=browse>`_,
-and follow up on the mailing list with a link to the sourceforge patch
-submissions. If you still do not hear anything within a week (this
-shouldn't happen!), send us a kind and gentle reminder on the mailing
-list.
-
-If you have made lots of local changes and do not want to a diff
-against the entire tree, but rather against a single directory or
-file, that is fine, but we do prefer svn diffs against HEAD.
-
-You should check out the guide to developing matplotlib to make sure
-your patch abides by our coding conventions
-:ref:`developers-guide-index`.
-
-
-.. _how-to-contribute-docs:
-
-Contribute to matplotlib documentation
-=========================================
-
-matplotlib is a big library, which is used in many ways, and the
-documentation we have only scratches the surface of everything it can
-do. So far, the place most people have learned all these features are
-through studying the examples (:ref:`how-to-search-examples`), which is a
-recommended and great way to learn, but it would be nice to have more
-official narrative documentation guiding people through all the dark
-corners. This is where you come in.
-
-There is a good chance you know more about matplotlib usage in some
-areas, the stuff you do every day, than any of the developers. *Just
-pulled your hair out compiling matplotlib for windows?* Write a FAQ or
-a section for the :ref:`installing` page. *Are you a digital signal
-processing wizard?* Write a tutorial on the signal analysis plotting
-functions like :func:`~matplotlib.pyplot.xcorr`,
-:func:`~matplotlib.pyplot.psd` and
-:func:`~matplotlib.pyplot.specgram`. *Do you use matplotlib with
-`django <ttp://www.djangoproject.com/>`_ or other popular web
-application servers?* Write a FAQ or tutorial and we'll find a place
-for it in the :ref:`users-guide-index`. *Bundle matplotlib in a `py2exe
-<http://www.py2exe.org/>`_ app?* ... I think you get the idea.
-
-matplotlib is documented using the `sphinx
-<http://sphinx.pocoo.org/index.html>`_ extensions to restructured text
-`ReST <http://docutils.sourceforge.net/rst.html>`_. sphinx is a
-extensible python framework for documentation projects which generates
-HTML and PDF, and is pretty easy to write; you can see the source for this
-document or any page on this site by clicking on *Show Source* link
-at the end of the page in the sidebar (or `here
-<../_sources/faq/howto_faq.txt>`_ for this document).
-
-The sphinx website is a good resource for learning sphinx, but we have
-put together a cheat-sheet at :ref:`documenting-matplotlib` which
-shows you how to get started, and outlines the matplotlib conventions
-and extensions, eg for including plots directly from external code in
-your documents.
-
-Once your documentation contributions are working (and hopefully
-tested by actually *building* the docs) you can submit them as a patch
-against svn. See :ref:`install-svn` and :ref:`how-to-submit-patch`.
-Looking for something to do? Search for ``TODO`` at :`search`.
-
-
-.. _how-to-search-examples:
-
-Search examples
-=========================================
-
-The nearly 300 code :ref:`examples-index` included with the matplotlib
-source distribution are full-text searchable from the :ref:`search`
-page, but sometimes when you search, you get a lot of results from the
-:ref:`api-index` or other documentation that you may not be interested in if
-you just want to find a complete, free-standing, working piece of
-example code. To facilitate example searches, we have tagged every
-page with the keyword ``codex`` for *code example* which shouldn't
-appear anywhere else on this site except in the FAQ and in every
-example. So if you want to search for an example that uses an ellipse,
-:ref:`search` for ``codex ellipse``.
-
-
-
-
-.. _howto-click-maps:
-
-Clickable images for HTML
-=========================
-
-Andrew Dalke of `Dalke Scientific <http://www.dalkescientific.com>`_
-has written a nice `article
-<http://www.dalkescientific.com/writings/diary/archive/2005/04/24/interactive_html.html>`_
-on how to make html click maps with matplotlib agg PNGs. We would
-also like to add this functionality to SVG and add a SWF backend to
-support these kind of images. If you are interested in contributing
-to these efforts that would be great.
-
.. _howto-set-zorder:
Control the depth of plot elements
-=============================================
+---------------------------------------
+
Within an axes, the order that the various lines, markers, text,
collections, etc appear is determined by the
:meth:`matplotlib.artist.Artist.set_zorder` property. The default
@@ -463,8 +293,6 @@
line, = ax.plot(x, y, zorder=10)
-
-
.. htmlonly::
See :ref:`pylab_examples-zorder_demo` for a complete example.
@@ -476,7 +304,7 @@
.. _howto-axis-equal:
Make the aspect ratio for plots equal
-===============================================
+-------------------------------------------
The Axes property :meth:`matplotlib.axes.Axes.set_aspect` controls the
aspect ratio of the axes. You can set it to be 'auto', 'equal', or
@@ -494,7 +322,7 @@
.. _howto-movie:
Make a movie
-======================
+-----------------------------------------------
If you want to take an animated plot and turn it into a movie, the
@@ -542,7 +370,7 @@
.. _howto-twoscale:
Multiple y-axis scales
-==================================
+-------------------------------
A frequent request is to have two scales for the left and right
y-axis, which is possible using :func:`~matplotlib.pyplot.twinx` (more
@@ -583,7 +411,7 @@
.. _howto-batch:
Generate images without having a window popup
-===========================================================
+--------------------------------------------------
The easiest way to do this is use an image backend (see
:ref:`what-is-a-backend`) such as Agg (for PNGs), PDF, SVG or PS. In
@@ -604,7 +432,7 @@
.. _howto-show
Use :func:`~matplotlib.pyplot.show`
-=====================================================
+------------------------------------------
The user interface backends need to start the GUI mainloop, and this
is what :func:`~matplotlib.pyplot.show` does. It tells matplotlib to
@@ -656,3 +484,188 @@
though we have made some pregress towards supporting blocking events.
+.. _howto-contribute:
+
+Contributing: howto
+=====================
+
+.. _how-to-submit-patch:
+
+Submit a patch
+-----------------
+
+First obtain a copy of matplotlib svn (see :ref:`install-svn`) and
+make your changes to the matplotlib source code or documentation and
+apply a `svn diff`. If it is feasible, do your diff from the top
+level directory, the one that contains :file:`setup.py`. Eg,::
+
+ > cd /path/to/matplotlib/source
+ > svn diff > mypatch.diff
+
+and then post your patch to the `matplotlib-devel
+<http://sourceforge.net/mail/?group_id=80706>`_ mailing list. If you
+do not get a response within 24 hours, post your patch to the
+sourceforge patch `tracker
+<http://sourceforge.net/tracker2/?atid=560722&group_id=80706&func=browse>`_,
+and follow up on the mailing list with a link to the sourceforge patch
+submissions. If you still do not hear anything within a week (this
+shouldn't happen!), send us a kind and gentle reminder on the mailing
+list.
+
+If you have made lots of local changes and do not want to a diff
+against the entire tree, but rather against a single directory or
+file, that is fine, but we do prefer svn diffs against HEAD.
+
+You should check out the guide to developing matplotlib to make sure
+your patch abides by our coding conventions
+:ref:`developers-guide-index`.
+
+
+.. _how-to-contribute-docs:
+
+Contribute to matplotlib documentation
+-----------------------------------------
+
+matplotlib is a big library, which is used in many ways, and the
+documentation we have only scratches the surface of everything it can
+do. So far, the place most people have learned all these features are
+through studying the examples (:ref:`how-to-search-examples`), which is a
+recommended and great way to learn, but it would be nice to have more
+official narrative documentation guiding people through all the dark
+corners. This is where you come in.
+
+There is a good chance you know more about matplotlib usage in some
+areas, the stuff you do every day, than many of the core developers
+who write most of the documentation. Just pulled your hair out
+compiling matplotlib for windows? Write a FAQ or a section for the
+:ref:`installing` page. Are you a digital signal processing wizard?
+Write a tutorial on the signal analysis plotting functions like
+:func:`~matplotlib.pyplot.xcorr`, :func:`~matplotlib.pyplot.psd` and
+:func:`~matplotlib.pyplot.specgram`. Do you use matplotlib with
+`django <http://www.djangoproject.com>`_ or other popular web
+application servers? Write a FAQ or tutorial and we'll find a place
+for it in the :ref:`users-guide-index`. Bundle matplotlib in a
+`py2exe <http://www.py2exe.org/>`_ app? ... I think you get the idea.
+
+matplotlib is documented using the `sphinx
+<http://sphinx.pocoo.org/index.html>`_ extensions to restructured text
+`ReST <http://docutils.sourceforge.net/rst.html>`_. sphinx is a
+extensible python framework for documentation projects which generates
+HTML and PDF, and is pretty easy to write; you can see the source for this
+document or any page on this site by clicking on *Show Source* link
+at the end of the page in the sidebar (or `here
+<../_sources/faq/howto_faq.txt>`_ for this document).
+
+The sphinx website is a good resource for learning sphinx, but we have
+put together a cheat-sheet at :ref:`documenting-matplotlib` which
+shows you how to get started, and outlines the matplotlib conventions
+and extensions, eg for including plots directly from external code in
+your documents.
+
+Once your documentation contributions are working (and hopefully
+tested by actually *building* the docs) you can submit them as a patch
+against svn. See :ref:`install-svn` and :ref:`how-to-submit-patch`.
+Looking for something to do? Search for `TODO <../search.html?q=todo>`_.
+
+
+
+
+.. _howto-webapp:
+
+Matplotlib in a web application server
+====================================================
+
+Many users report initial problems trying to use maptlotlib in web
+application servers, because by default matplotlib ships configured to
+work with a graphical user interface which may require an X11
+connection. Since many barebones application servers do not have X11
+enabled, you may get errors if you don't configure matplotlib for use
+in these environments. Most importantly, you need to decide what
+kinds of images you want to generate (PNG, PDF, SVG) and configure the
+appropriate default backend. For 99% of users, this will be the Agg
+backend, which uses the C++ `antigrain <http://antigrain.com>`_
+rendering engine to make nice PNGs. The Agg backend is also
+configured to recognize requests to generate other output formats
+(PDF, PS, EPS, SVG). The easiest way to configure matplotlib to use
+Agg is to call::
+
+ # do this before importing pylab or pyplot
+ import matplotlib
+ matplotlib.use('Agg')
+ import matplotlib.pyplot as plt
+
+For more on configuring your backend, see
+:ref:`what-is-a-backend`.
+
+Alternatively, you can avoid pylab/pyplot altogeher, which will give
+you a little more control, by calling the API directly as shown in
+`agg_oo.py <http://matplotlib.sf.net/examples/api/agg_oo.py>`_ .
+
+You can either generate hardcopy on the filesystem by calling savefig::
+
+ # do this before importing pylab or pyplot
+ import matplotlib
+ matplotlib.use('Agg')
+ import matplotlib.pyplot as plt
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.plot([1,2,3])
+ fig.savefig('test.png')
+
+or by saving to a file handle::
+
+ import sys
+ fig.savefig(sys.stdout)
+
+
+matplotlib with apache
+------------------------------------
+
+TODO; see :ref:`how-to-contribute-docs`.
+
+matplotlib with django
+------------------------------------
+
+TODO; see :ref:`how-to-contribute-docs`.
+
+matplotlib with zope
+----------------------------------
+
+TODO; see :ref:`how-to-contribute-docs`.
+
+.. _howto-click-maps:
+
+Clickable images for HTML
+-------------------------
+
+Andrew Dalke of `Dalke Scientific <http://www.dalkescientific.com>`_
+has written a nice `article
+<http://www.dalkescientific.com/writings/diary/archive/2005/04/24/interactive_html.html>`_
+on how to make html click maps with matplotlib agg PNGs. We would
+also like to add this functionality to SVG and add a SWF backend to
+support these kind of images. If you are interested in contributing
+to these efforts that would be great.
+
+
+.. _how-to-search-examples:
+
+Search examples
+=========================================
+
+The nearly 300 code :ref:`examples-index` included with the matplotlib
+source distribution are full-text searchable from the :ref:`search`
+page, but sometimes when you search, you get a lot of results from the
+:ref:`api-index` or other documentation that you may not be interested in if
+you just want to find a complete, free-standing, working piece of
+example code. To facilitate example searches, we have tagged every
+page with the keyword ``codex`` for *code example* which shouldn't
+appear anywhere else on this site except in the FAQ and in every
+example. So if you want to search for an example that uses an ellipse,
+:ref:`search` for ``codex ellipse``.
+
+
+
+
+
+
+
Modified: trunk/matplotlib/doc/make.py
===================================================================
--- trunk/matplotlib/doc/make.py 2008-10-17 18:20:09 UTC (rev 6249)
+++ trunk/matplotlib/doc/make.py 2008-10-17 18:51:10 UTC (rev 6250)
@@ -27,13 +27,14 @@
def figs():
os.system('cd users/figures/ && python make.py')
+def examples():
+ 'make the rest examples'
+ os.system('cd examples; svn-clean; python gen_rst.py')
+
def html():
check_build()
- # build the literal include examples for searchable examples
- os.system('cd examples; python gen_rst.py')
-
-
-
+ if not os.path.exists('examples/index.rst'):
+ examples()
#figs()
if os.system('sphinx-build -b html -d build/doctrees . build/html'):
raise SystemExit("Building HTML failed.")
@@ -67,13 +68,11 @@
print 'latex build has not been tested on windows'
def clean():
- if os.path.exists('build'):
- shutil.rmtree('build')
- for fname in glob.glob('pyplots/*.png') + glob.glob('pyplots/*.pdf'):
- os.remove(fname)
+ os.system('svn-clean')
def all():
#figs()
+ examples()
html()
latex()
@@ -84,6 +83,7 @@
'clean':clean,
'sf':sf,
'sfpdf':sfpdf,
+ 'examples':examples,
'all':all,
}
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Matplotlib-checkins mailing list
Matplotlib-checkins@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
