Revision: 6244
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6244&view=rev
Author: jdh2358
Date: 2008-10-17 17:21:56 +0000 (Fri, 17 Oct 2008)
Log Message:
-----------
more faqs and codex example search keyword
Modified Paths:
--------------
trunk/matplotlib/doc/examples/gen_rst.py
trunk/matplotlib/doc/faq/howto_faq.rst
trunk/matplotlib/doc/faq/installing_faq.rst
trunk/matplotlib/doc/faq/troubleshooting_faq.rst
Modified: trunk/matplotlib/doc/examples/gen_rst.py
===================================================================
--- trunk/matplotlib/doc/examples/gen_rst.py 2008-10-17 16:03:23 UTC (rev
6243)
+++ trunk/matplotlib/doc/examples/gen_rst.py 2008-10-17 17:21:56 UTC (rev
6244)
@@ -114,7 +114,7 @@
contents = '\n'.join([' %s'%row.rstrip() for row in
contents.split('\n')])
fh.write(contents)
- fh.write('\n\n')
+ fh.write('\n\nKeyword: codex (see :ref:`how-to-search-examples`)')
fh.close()
fhsubdirIndex.close()
Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 16:03:23 UTC (rev
6243)
+++ trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 17:21:56 UTC (rev
6244)
@@ -9,7 +9,7 @@
.. _howto-findobj:
-How do I find all the objects in my figure of a certain type?
+Find all objects in figure of a certain type
=============================================================
Every matplotlib artist (see :ref:`artist-tutorial`) has a method
@@ -35,7 +35,7 @@
.. _howto-transparent:
-How do I save transparent figures?
+Save transparent figures
==================================
The :meth:`~matplotlib.pyplot.savefig` command has a keyword argument
@@ -64,7 +64,7 @@
.. _howto-subplots-adjust:
-How do I move the edge of my axes area over to make room for my tick labels?
+Move the edge of an axes to make room for tick labels
============================================================================
For subplots, you can control the default spacing on the left, right,
@@ -114,7 +114,7 @@
.. _howto-auto-adjust:
-How do I automatically make room for my tick labels?
+Automatically make room for tick labels
====================================================
In most use cases, it is enough to simpy change the subplots adjust
@@ -148,7 +148,7 @@
.. _howto-ticks:
-How do I configure the tick linewidths?
+Configure the tick linewidths
=======================================
In matplotlib, the ticks are *markers*. All
@@ -174,7 +174,7 @@
.. _howto-align-label:
-How do I align my ylabels across multiple subplots?
+Align my ylabels across multiple subplots
===================================================
If you have multiple subplots over one another, and the y data have
@@ -191,7 +191,7 @@
.. _howto-webapp:
-How do I use matplotlib in a web application server?
+Matplotlib in a web application server
====================================================
Many users report initial problems trying to use maptlotlib in web
@@ -237,17 +237,17 @@
fig.savefig(sys.stdout)
-How do I use matplotlib with apache?
+matplotlib with apache
------------------------------------
TODO
-How do I use matplotlib with django?
+matplotlib with django
------------------------------------
TODO
-How do I use matplotlib with zope?
+matplotlib with zope
----------------------------------
TODO
@@ -255,7 +255,7 @@
.. _date-index-plots:
-How do I skip dates where there is no data?
+Skip dates where there is no data
===========================================
When plotting time series, eg financial time series, one often wants
@@ -292,7 +292,7 @@
.. _point-in-poly:
-How do I test whether a point is inside a polygon?
+Test whether a point is inside a polygon
==================================================
The :mod:`matplotlib.nxutils` provides two high performance methods:
@@ -340,7 +340,7 @@
.. _how-to-submit-patch:
-How do I submit a patch?
+Submit a patch
========================
First obtain a copy of matplotlib svn (see :ref:`install-svn`) and
@@ -370,6 +370,72 @@
: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
@@ -385,7 +451,7 @@
.. _howto-set-zorder:
-How do I control the depth of plot elements?
+Control the depth of plot elements
=============================================
Within an axes, the order that the various lines, markers, text,
@@ -409,7 +475,7 @@
.. _howto-axis-equal:
-How to I make the aspect ratio for plots equal?
+Make the aspect ratio for plots equal
===============================================
The Axes property :meth:`matplotlib.axes.Axes.set_aspect` controls the
@@ -427,13 +493,13 @@
.. _howto-movie:
-How do I make a movie?
+Make a movie
======================
If you want to take an animated plot and turn it into a movie, the
best approach is to save a series of image files (eg PNG) and use an
-external tool to convert them to a movie. You can use ` mencoder
+external tool to convert them to a movie. You can use `mencoder
<http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html>`_,
which is part of the `mplayer <http://www.mplayerhq.hu>`_ suite
for this::
@@ -475,7 +541,7 @@
.. _howto-twoscale:
-Can I have multiple y-axis scales?
+Multiple y-axis scales
==================================
A frequent request is to have two scales for the left and right
@@ -514,10 +580,10 @@
See :ref:`api-two_scales` for a complete example
-.. _howto-batchmode:
+.. _howto-batch:
-Can I just generate images without having a window popup?
-=====================================================
+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
@@ -535,21 +601,17 @@
.. seealso::
:ref:`howto-webapp`
- ('SHOW',
- "What's up with 'show'? Do I have to use it?",
- """
-
.. _howto-show
-How should I use :func:`~matplotlib.pyplot.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
raise all of the figure windows and start the mainloop. Because the
mainloop is blocking, you should only call this once per script, at
the end. If you are using matplotlib to generate images only and do
-not want a user interface window, you can skip it (see
+not want a user interface window, you do not need to call ``show`` (see
:ref:`howto-batch` and :ref:`what-is-a-backend`).
@@ -565,8 +627,8 @@
It is *possible* to force matplotlib to draw after every command,
which is what you usually want when working interactively at the
-python console, but in a script you want to defer all drawing until
-the script has executed (see :ref:`mpl-shell`). This is especially
+python console (see :ref:`mpl-shell`), but in a script you want to
+defer all drawing until the script has executed. This is especially
important for complex figures that take some time to draw.
:func:`~matplotlib.pyplot.show` is designed to tell matplotlib that
you're all done issuing commands and you want to draw the figure now.
Modified: trunk/matplotlib/doc/faq/installing_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/installing_faq.rst 2008-10-17 16:03:23 UTC (rev
6243)
+++ trunk/matplotlib/doc/faq/installing_faq.rst 2008-10-17 17:21:56 UTC (rev
6244)
@@ -8,12 +8,12 @@
.. contents::
-How do I report a compilation problem?
+Report a compilation problem
======================================
See :ref:`reporting-problems`.
-matplotlib compiled fine, but I can't get anything to plot
+matplotlib compiled fine, but nothing shows up with plot
==========================================================
The first thing to try is a :ref:`clean install <clean-install>` and see if
@@ -42,7 +42,7 @@
.. _clean-install:
-How do I cleanly rebuild and reinstall everything?
+Cleanly rebuild and reinstall everything
==================================================
The steps depend on your platform and installation method.
@@ -93,7 +93,7 @@
.. _install-svn:
-How to install from svn?
+Install from svn
========================
Checking out the main source::
@@ -236,7 +236,7 @@
.. _pygtk-2.4:
-How do I compile matplotlib with PyGTK-2.4?
+Compile matplotlib with PyGTK-2.4
-------------------------------------------
There is a `bug in PyGTK-2.4`_. You need to edit
@@ -269,11 +269,11 @@
.. _easy-install-osx-egg:
-How can I easy_install my egg?
+easy_install from egg?
------------------------------
-I downloaded the egg for 0.98 from the matplotlib webpages,
-and I am trying to ``easy_install`` it, but I am getting an error::
+Some users have reported problems with the egg for 0.98 from the
+matplotlib download site, with ``easy_install``, getting an error::
> easy_install ./matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
Processing matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
@@ -296,7 +296,7 @@
.. _windows-installers:
-Where can I get binary installers for windows?
+Binary installers for windows
----------------------------------------------
If you have already installed python, you can use one of the
Modified: trunk/matplotlib/doc/faq/troubleshooting_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/troubleshooting_faq.rst 2008-10-17 16:03:23 UTC
(rev 6243)
+++ trunk/matplotlib/doc/faq/troubleshooting_faq.rst 2008-10-17 17:21:56 UTC
(rev 6244)
@@ -8,7 +8,7 @@
.. _matplotlib-version:
-What is my matplotlib version?
+Obtaining matplotlib version
==============================
To find out your matplotlib version number, import it and print the
@@ -21,8 +21,8 @@
.. _locating-matplotlib-install:
-Where is matplotlib installed?
-==============================
+:file:`matplotlib` install location
+====================================
You can find what directory matplotlib is installed in by importing it
and printing the ``__file__`` attribute::
@@ -33,8 +33,8 @@
.. _locating-matplotlib-config-dir:
-Where is my .matplotlib directory?
-==================================
+:file:`.matplotlib` directory location
+========================================
Each user has a :file:`.matplotlib/` directory which may contain a
:ref:`matplotlibrc <customizing-with-matplotlibrc-files>` file and various
@@ -61,11 +61,11 @@
.. _reporting-problems:
-How do I report a problem?
+Report a problem
==========================
If you are having a problem with matplotlib, search the mailing
-lists first: There's a good chance someone else has already run into
+lists first: there's a good chance someone else has already run into
your problem.
If not, please provide the following information in your e-mail to the
@@ -128,7 +128,7 @@
.. _svn-trouble:
-I am having trouble with a recent svn update, what should I do?
+Problems with recent svn versions
===============================================================
First make sure you have a clean build and install (see
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
