ANN: matplotlib website 1.0

Community matplotlib-users
1

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/py4science/examples/sphinx_template2

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  http://conference.scipy.org/proceedings/SciPy2008/paper_6/

JDH

2

The new webpage looks great, sphinx has really meant a lot for the documentation in the scientific projects.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

But I have some problems using the template from windows (python2.5). From a fresh checkout of the sphinx_template2 from svn and running
the following in that folder:

C:\python\mpl_template>sphinx-build -b html -d build/doctrees .
build/html
Sphinx v0.5, building html
loading pickled environment... not found
building [html]: targets for 10 source files that are out of date
updating environment: 10 added, 0 changed, 0 removed
reading sources... index model/api_docs model/index model/introduction model/nex
t_steps model/sphinx_helpers building C:\python\mpl_template\pyplots\elegant
.py
ERROR: File `C:pythonmpl_templatepyplotselegant.py` not found.
simulations/finale already have C:\python\mpl_template\pyplots\elegant.py
simulations/index simulations/introduction simulations/preliminary building
C:\python\mpl_template\pyplots\hairy.py
ERROR: File `C:pythonmpl_templatepyplotshairy.py` not found.

pickling environment... done
checking consistency... done
preparing documents... done
writing output... index model/api_docs model/index model/introduction model/next
_steps model/sphinx_helpers simulations/finale simulations/index simulations/int
roduction simulations/preliminary
WARNING: C:\python\mpl_template\model\sphinx_helpers.rst:177: (WARNING/2) 'dot'
called with invalid arguments
writing additional files... genindex modindex search
copying images... _static\elegant.pdf _static\hairy.pdf _static\elegant.png _sta
tic\hairy.png
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.

There are two errors with very strange filenames, it looks like the path
separator has disappeared.

Any both the graphs elegant and hairy are generated but they are
empty, both the png and pdf. Any ideas?

/Jörgen

3

John Hunter wrote:

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

It all does look rather good and shiny :slight_smile:

However, on the page: http://matplotlib.sourceforge.net/users/screenshots.html
the following link does not work:
http://matplotlib.sourceforge.net/users/examples/pylab_examples/bar_stacked.py

Also, the screenshots don't tie up with those listed in the sidebar on the main page - is there a good reason for this? :slight_smile:

Thanks,

···

--
Neil

4

Looks great but there are too many errors:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

I'm not a geek and I do not care about w3c small warnings but it would be so nice to have a xhtml compliant website (as close as possible)

From an "artistic" point of view, I would put more emphasis on the screenshot (pylab purpose is to produce *very* nice images...)

xavier

···

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  Proceedings of the Python in Science Conference (SciPy): Matplotlib Solves the Riddle of the Sphinx

JDH

-------------------------------------------------------------------------
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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options

5

This has now been fixed in SVN.

index.html is the only page that includes hand-written HTML. If you see any errors of this nature on other pages, please file bugs with Sphinx and/or docutils.

Cheers,
Mike

Xavier Gnata wrote:

···

Looks great but there are too many errors:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

I'm not a geek and I do not care about w3c small warnings but it would be so nice to have a xhtml compliant website (as close as possible)

From an "artistic" point of view, I would put more emphasis on the screenshot (pylab purpose is to produce *very* nice images...)

xavier

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  Proceedings of the Python in Science Conference (SciPy): Matplotlib Solves the Riddle of the Sphinx

JDH

-------------------------------------------------------------------------
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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  
-------------------------------------------------------------------------
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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

6

While I like the redesign (and Sphinx in general), it seems some
information has gone missing, particularly with regards to the API
documentation.

For example, ticker.py has a tonne of useful information in the
docstring about how to set up formatters and tickers. For some reason
I just cannot find this information on the redesign. The best I get
is a single line ("class matplotlib.axis.Ticker") on the the Axis
class API page. On the epydoc based system, it was easy to find.
Perhaps there's merit in making the API documentation (as spat out by
epydoc or equivalent) available in parallel to the Sphinx
documentation?

Cheers,

···
7

Some of the documentation has not yet been reformatted to reST for Sphinx.

There is a status page here:

http://matplotlib.sourceforge.net/devel/outline.html

(And I'm embarrassed to note that I'm slated to update the ticker module... :wink:

As to whether we provide the old docs in parallel -- I'll leave that question to the John or others.

Mike

Anthony Floyd wrote:

···

While I like the redesign (and Sphinx in general), it seems some
information has gone missing, particularly with regards to the API
documentation.

For example, ticker.py has a tonne of useful information in the
docstring about how to set up formatters and tickers. For some reason
I just cannot find this information on the redesign. The best I get
is a single line ("class matplotlib.axis.Ticker") on the the Axis
class API page. On the epydoc based system, it was easy to find.
Perhaps there's merit in making the API documentation (as spat out by
epydoc or equivalent) available in parallel to the Sphinx
documentation?

Cheers,
>

-------------------------------------------------------------------------
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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

8

Some of the documentation has not yet been reformatted to reST for Sphinx.

There is a status page here:

http://matplotlib.sourceforge.net/devel/outline.html

Ah, thanks!

[snip]

As to whether we provide the old docs in parallel -- I'll leave that
question to the John or others.

I think that it's critical that documentation is not 'lost' (even
temporarily) during the conversion process. Especially for novices or
even for just quick class-checking for advanced users. And while I
suppose people who really need the documentation will run epydoc
against it themselves (guilty) it seems odd to have a reduction of
information on the website.

Just my $0.02. Keep up the good work!

···

On Wed, Oct 22, 2008 at 11:00 AM, Michael Droettboom <mdroe@...86...> wrote:

9

I think it is a good idea to put a copy of the pydoc autogenerated
module docs up, but I won't be able to get to it until next week.
Ditto for the old user's guide.

In the meantime, I've added matplotlib.ticker to the new docs:

  http://matplotlib.sourceforge.net/api/ticker_api.html

JDH

···

On Wed, Oct 22, 2008 at 1:38 PM, Anthony Floyd <anthonyfloyd@...287...> wrote:

On Wed, Oct 22, 2008 at 11:00 AM, Michael Droettboom <mdroe@...86...> wrote:

Some of the documentation has not yet been reformatted to reST for Sphinx.

There is a status page here:

http://matplotlib.sourceforge.net/devel/outline.html

Ah, thanks!

[snip]

As to whether we provide the old docs in parallel -- I'll leave that
question to the John or others.

10

ok.
It is way better now but still:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

hum I should spend some time on this because:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2Fgallery.html&charset=(detect+automatically)&doctype=Inline&group=0&user-agent=W3C_Validator%2F1.591

but this gallery is so nice...

Xavier

···

This has now been fixed in SVN.

index.html is the only page that includes hand-written HTML. If you see any errors of this nature on other pages, please file bugs with Sphinx and/or docutils.

Cheers,
Mike

Xavier Gnata wrote:

Looks great but there are too many errors:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

I'm not a geek and I do not care about w3c small warnings but it would be so nice to have a xhtml compliant website (as close as possible)

From an "artistic" point of view, I would put more emphasis on the screenshot (pylab purpose is to produce *very* nice images...)

xavier

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  Proceedings of the Python in Science Conference (SciPy): Matplotlib Solves the Riddle of the Sphinx

JDH

-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
      
-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  

11

Fixed. These errors were all in new content.

Any comments on the content? ... :slight_smile:

Xavier Gnata wrote:

···

ok.
It is way better now but still:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

hum I should spend some time on this because:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2Fgallery.html&charset=(detect+automatically)&doctype=Inline&group=0&user-agent=W3C_Validator%2F1.591

but this gallery is so nice...

Xavier

This has now been fixed in SVN.

index.html is the only page that includes hand-written HTML. If you see any errors of this nature on other pages, please file bugs with Sphinx and/or docutils.

Cheers,
Mike

Xavier Gnata wrote:

Looks great but there are too many errors:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

I'm not a geek and I do not care about w3c small warnings but it would be so nice to have a xhtml compliant website (as close as possible)

From an "artistic" point of view, I would put more emphasis on the screenshot (pylab purpose is to produce *very* nice images...)

xavier

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  Proceedings of the Python in Science Conference (SciPy): Matplotlib Solves the Riddle of the Sphinx

JDH

-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
      
-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

12

I'll comment that the new site looks absolutely awesome. I've turned
quite a few heads around here when I show people the new site and docs,
especially the gallery. Great work guys!

One question, how is the list of "plotting commands" on the main page
generated? Is it just the pyplot API? Right now I know at the very
least it does not list "barbs" as a plotting command.

Ryan

Michael Droettboom wrote:

···

Fixed. These errors were all in new content.

Any comments on the content? ... :slight_smile:

Xavier Gnata wrote:

ok.
It is way better now but still:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

hum I should spend some time on this because:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2Fgallery.html&charset=(detect+automatically)&doctype=Inline&group=0&user-agent=W3C_Validator%2F1.591

but this gallery is so nice...

Xavier

This has now been fixed in SVN.

index.html is the only page that includes hand-written HTML. If you
see any errors of this nature on other pages, please file bugs with
Sphinx and/or docutils.

Cheers,
Mike

Xavier Gnata wrote:

Looks great but there are too many errors:
http://validator.w3.org/check?uri=http%3A%2F%2Fmatplotlib.sourceforge.net%2F&charset=(detect+automatically)&doctype=Inline&group=0

I'm not a geek and I do not care about w3c small warnings but it
would be so nice to have a xhtml compliant website (as close as
possible)

From an "artistic" point of view, I would put more emphasis on the
screenshot (pylab purpose is to produce *very* nice images...)

xavier

We've been working behind the scenes on a new documentation system for
matplotlib, which integrates the web site, API documentation and PDF
guide into a single source of sphinx/rest documents which are easier
to maintain and extend, hopefully leading to better and more
up-to-date docs.

We went live with the new site yesterday:

  http://matplotlib.sf.net

so check it out and let us know if something is broken or missing. We
don't have everything that was on the old site (some stuff from the
FAQ, "what's new" and "user's guide" has not been ported over) but we
do have should be current, searchable, indexed and cross-linked.

Thanks to Darren Dale who spear-headed the effort to use the sphinx
documentation, and to the developers who have contributed, especially
Michael Droettboom, who has developed several nice sphinx extensions
to do inheritance diagrams, syntax highlighting of ipython sessions,
and inline plotting. As an example we can include plots in our API
documentation, see

http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.acorr

We embed these plots with a "plot" directive that generates the
figures from external code at documentation build time, which
guarantees that the example code you see in the docs generate the
figures you see in the docs. For example, in the acorr docstring, all
we have to do is::

        **Example:**

        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py

and the figure and source code links automagically appear in the docs.

Because some of these extensions are generally useful, Michael,
Fernando and I have been working on a "sphinx_template" which contains
the template of a sphinx documentation project with these extensions
in place, so people who want to get started using sphinx (the official
documentation system for python, numpy, ipython and matplotlib) can do
so more easily. Right now it is available in svn

  > svn co
matplotlib download | SourceForge.net

and see the README in the checkout directory. Michael also did a talk
on matplotlib's use of sphinx and the sphinx template at the last
scipy conference. We're still waiting for the videos of the talks to
be posted (can someone poke someone?) but you can see the talk PDF
from the proceedings here:

  Proceedings of the Python in Science Conference (SciPy): Matplotlib Solves the Riddle of the Sphinx

JDH

-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
      
-------------------------------------------------------------------------

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-users mailing list
Matplotlib-users@lists.sourceforge.net
matplotlib-users List Signup and Options
  
--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma

13

Right now it is just manually generated and should cover the pyplot
module and may be out of date. I started working on a set of tables,
of all the commands in pylab, organized by the module they come from,
with links to the docs (eg to the numpy docs for numpy commands) but
haven't finished. If you would like to update anything missing from
the table (doc/_templates/index.html) that would be great.

JDH

···

On Thu, Oct 23, 2008 at 9:53 AM, Ryan May <rmay31@...287...> wrote:

I'll comment that the new site looks absolutely awesome. I've turned
quite a few heads around here when I show people the new site and docs,
especially the gallery. Great work guys!

One question, how is the list of "plotting commands" on the main page
generated? Is it just the pyplot API? Right now I know at the very
least it does not list "barbs" as a plotting command.

14

John Hunter wrote:

···

On Thu, Oct 23, 2008 at 9:53 AM, Ryan May <rmay31@...287...> wrote:

I'll comment that the new site looks absolutely awesome. I've turned
quite a few heads around here when I show people the new site and docs,
especially the gallery. Great work guys!

One question, how is the list of "plotting commands" on the main page
generated? Is it just the pyplot API? Right now I know at the very
least it does not list "barbs" as a plotting command.

Right now it is just manually generated and should cover the pyplot
module and may be out of date. I started working on a set of tables,
of all the commands in pylab, organized by the module they come from,
with links to the docs (eg to the numpy docs for numpy commands) but
haven't finished. If you would like to update anything missing from
the table (doc/_templates/index.html) that would be great.

I've done it for barbs and I'll see if I notice anything else as time
allows. Obviously I'm biased towards certain functionality. :slight_smile: I'm
guessing you guys have to do regenerate the docs and push them somewhere
before any of this becomes live.

Ryan

--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma

15

I've done it for barbs and I'll see if I notice anything else as time
allows. Obviously I'm biased towards certain functionality. :slight_smile: I'm
guessing you guys have to do regenerate the docs and push them somewhere
before any of this becomes live.

Yes, but it's pretty easy. To build and update from the docs dir, I just do

python make.py html sf

I've pushed your changes out -- thanks!

JDH

···

On Thu, Oct 23, 2008 at 10:51 AM, Ryan May <rmay31@...287...> wrote:

16

John Hunter wrote:

···

On Thu, Oct 23, 2008 at 10:51 AM, Ryan May <rmay31@...287...> wrote:

I've done it for barbs and I'll see if I notice anything else as time
allows. Obviously I'm biased towards certain functionality. :slight_smile: I'm
guessing you guys have to do regenerate the docs and push them somewhere
before any of this becomes live.

Yes, but it's pretty easy. To build and update from the docs dir, I just do

python make.py html sf

I've pushed your changes out -- thanks!

Thanks. Now, did I do something wrong, because the pyplot api page
doesn't show the example I added to the barbs docstring.

Ryan

--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma

17

Ryan May wrote:

John Hunter wrote:
  

I've done it for barbs and I'll see if I notice anything else as time
allows. Obviously I'm biased towards certain functionality. :slight_smile: I'm
guessing you guys have to do regenerate the docs and push them somewhere
before any of this becomes live.

Yes, but it's pretty easy. To build and update from the docs dir, I just do

python make.py html sf
      

I've pushed your changes out -- thanks!
    
Thanks. Now, did I do something wrong, because the pyplot api page
doesn't show the example I added to the barbs docstring.
  

It's probably just that John didn't rebuild matplotlib itself and then clean before republishing the docs. Your change works for me locally.

Cheers,
Mike

···

On Thu, Oct 23, 2008 at 10:51 AM, Ryan May <rmay31@...287...> wrote:

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

18

Michael Droettboom wrote:

Ryan May wrote:

John Hunter wrote:

Yes, but it's pretty easy. To build and update from the docs dir, I
just do

python make.py html sf
      

I've pushed your changes out -- thanks!
    
Thanks. Now, did I do something wrong, because the pyplot api page
doesn't show the example I added to the barbs docstring.
  

It's probably just that John didn't rebuild matplotlib itself and then
clean before republishing the docs. Your change works for me locally.

Thanks. Just wanted to make sure I wasn't being "a little special".

Ryan

···

--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma

19

I think the trick is I also have to "touch" the pymods_api.rst doc. I
did install the latest mpl from src before building but it didn't
work. So I am going to see if touching the rst doc helps.

Yep -- just confirmed

  http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.barbs

Unfortunately, I have to run catch a plane so I will not be able to
followup for a while.

JDH

···

On Thu, Oct 23, 2008 at 11:44 AM, Michael Droettboom <mdroe@...86...> wrote:

It's probably just that John didn't rebuild matplotlib itself and then clean
before republishing the docs. Your change works for me locally.

20

John Hunter wrote:

I've done it for barbs and I'll see if I notice anything else as time
allows. Obviously I'm biased towards certain functionality. :slight_smile: I'm
guessing you guys have to do regenerate the docs and push them somewhere
before any of this becomes live.

Yes, but it's pretty easy. To build and update from the docs dir, I just do

python make.py html sf

I've pushed your changes out -- thanks!

Related to the barbs non-updating issue, I just noticed that the
pyplot.clabel docs online are woefully out of date while the docstring
is actually quite nice. I just had someone come by asking a question
about clabel that would have been in the docs had the online ones been
up to date. Do we have some kind of problem with getting these docs to
update when we build them? Is there something I can help with here?

Ryan

···

On Thu, Oct 23, 2008 at 10:51 AM, Ryan May <rmay31@...287...> wrote:

--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma