matplotlib-devel Mailing List for matplotlib

Darren,
I think this is a GREAT idea. I've been trying to free up some resources to
work on a better MPL user's guide for our users this year. If I can swing
it, perhaps we can help contribute some sections.
Given that we use the units system extensively, we'd probably have some
sections that are pure MPL and a lot of sections that use our custom time
and unit types. It might be nice if there were hooks where we could build
our own local docs in with the standard docs. I'm guess that would be
fairly easy...
Ted
> -----Original Message-----
> From: mat...@li...
> [mailto:mat...@li...] On Behalf Of
> Darren Dale
> Sent: Thursday, May 22, 2008 6:15 AM
> To: mat...@li...
> Subject: Re: [matplotlib-devel] future of mpl documentation
> 
> I am planning on starting to overhaul the documentation using Sphinx
> next
> week. I have been experimenting with Sphinx to create some
> documentation for
> a project at work
> (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
> http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really
> impressed
> with Sphinx, I think it will allow us to unify the matplotlib
> docstrings,
> webpage and the pdf copies of the users guide / developers guide / API
> reference.
> 
> In order to integrate all the doumentation together, it would be best
> if I
> could convert the mpl docstrings to ReST. This would be quite a big
> project,
> and I don't want to commit us before we have a chance to evaluate the
> results, so I guess a documentation branch would be appropriate. Could
> someone help guide me through the process of creating a new branch and
> pulling in some of the older doc sources? Aside from Johns recent post
> about
> using svnmerge, is there anything else I should keep in mind while
> trying to
> keep the branch in sync with the trunk?
> 
> Thanks,
> Darren
> 
> -----------------------------------------------------------------------
> --
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> Checked by AVG.
> Version: 8.0.100 / Virus Database: 269.24.0/1460 - Release Date:
> 5/22/2008 7:06 AM

Hi,
We are developing an application for analysing and displaying
neutron scattering data in Python, and a big part of this 
requires good graphics. We are looking for a user interface
developer with a science background to help us. Some of this 
effort will be to improve the matplotlib backend.
If you know any developers who would be interested in such
a project, please direct them to our job announcement:
 http://reflectometry.org/danse/software-job.html
Thanks in advance,
	- Paul

On Thu, May 22, 2008 at 06:12:15PM -0400, Darren Dale wrote:
> http://dale.chess.cornell.edu/~darren/temp/XPaXS/reflectivity.xml#matrix-method
> 
> There is a "show source" link on the left that shows the original ReST wource 
> for the current page, here is the math markup:
> 
> :math:`sin(x_n^2)`
> 
> .. math::
> 
> \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}
> 
> The latex file also renders the equations nicely.
I didn't notice since Safari 3.1.1 renders it as:
 sin(xn2)
 <integral>-<inf><inf>ei<phi>1+x2ei<phi>1+x2
where <char> is the write symbol, but all symbols are the same size and no spacing
or other layout.
It looks okay in Firefox 2.0.0.14 (though it did complain about missing the mathml
fonts).
IE 7 displays the xml tree.
	- Paul

On Thursday 22 May 2008 5:03:31 pm Paul Kienzle wrote:
> On Thu, May 22, 2008 at 02:44:43PM -0400, Darren Dale wrote:
> > Here is the docstring for the texmanager module:
>
> I saw this package for math markup mentioned in the docutils FAQ:
>
> http://docutils.sourceforge.net/sandbox/jensj/latex_math/
>
> It should allow you to include latex markup in the docstrings.
>
> Has anyone tried it?
Yes, Jens Mortenson pointed out it out on sphinx-dev a while back, it is 
already included in our trunk :) Georg Brandl kindly added a new option in 
svn so we can produce files with .xml file extensions instead of .html, which 
are required to render mathml.
I dont have an example yet in the matplotlib docs, but I played with it in my 
XPaXS documents, you can see it here:
http://dale.chess.cornell.edu/~darren/temp/XPaXS/reflectivity.xml#matrix-method
There is a "show source" link on the left that shows the original ReST wource 
for the current page, here is the math markup:
:math:`sin(x_n^2)`
.. math::
 \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}
The latex file also renders the equations nicely.
Darren

I just committed the beginnings of a Sphinx-based documentation to svn. It 
includes a section explaining how to get up and running with sphinx, its 
*really easy*: 
http://dale.chess.cornell.edu/~darren/temp/matplotlib/Users_Guide/documenting_mpl.xml
Here is the same documentation in plain text:
**********************
Documenting Matplotlib
**********************
The documentation for matplotlib is generated from ReStructured Text
using the Sphinx_ documentation generation tool. Sphinx-0.4 or later 
is required to generate xml files to render mathematical expressions 
with mathml. Currently this means we need to install from the svn 
repository by doing::
 svn co http://svn.python.org/projects/doctools/trunk sphinx
 cd sphinx
 python setup.py install
.. _Sphinx: http://sphinx.pocoo.org/
The documentation sources are found in the doc/ directory in the trunk.
To build the users guid in html format, cd into doc/users_guide and do::
 python make.py html
you can also pass a ``latex`` flag to make.py to build a pdf, or pass no 
arguments to build everything. The same procedure can be followed for
the sources in doc/api_reference.
The actual ReStructured Text files are kept in doc/users_guide/source
and doc/api_reference/source. The main entry point is index.txt. 
Additional files can be added by including their base file name 
(dropping the .txt extension) in the table of contents. It is also 
possible to include other documents through the use of an include 
statement. For example, in the Developers Guide, index.txt lists 
coding_guide, which automatically inserts coding_guide.txt. 
coding_guide.txt is just a placeholder, it contains one line only to 
gets its contents from the CODING_GUIDE file in the trunk: 
``.. include:: ../../CODING_GUIDE``.
The output produced by Sphinx can be configured by editing the conf.py
files located in the documentation source directories.
The Sphinx website contains plenty of documentation_ concerning ReST
markup and working with Sphinx in general.
.. _documentation: http://sphinx.pocoo.org/contents.html

On Thu, May 22, 2008 at 02:44:43PM -0400, Darren Dale wrote:
> Here is the docstring for the texmanager module:
I saw this package for math markup mentioned in the docutils FAQ:
 http://docutils.sourceforge.net/sandbox/jensj/latex_math/
It should allow you to include latex markup in the docstrings.
Has anyone tried it?
	- Paul

On Thu, May 22, 2008 at 1:44 PM, Darren Dale <dar...@co...> wrote:
> We have a lot of flexibility here. I prefer to pull from a few smaller
> documents using rest include statements or table of contents directives.
> Ipython, on the other hand, has the whole guide included in one file.
I would like to go with smaller files if it is possible, since it
would be nice to have little simple text documents (coding_guide.txt,
migration.txt, artist_tutorial.txt) that people can read in their
editors which are assembled into the docs for PDF and HTML
>> I don't think we will want to have one master
>> PDF for the user's guide, developer's guide and api docs (the
>> autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
>> pages along).
>
> Ok. It is easy enough to break them up into separate documents. I'll work on
> it this afternoon. Should we have a separate developers guide, or could it be
> included in the users guide?
Since the developers stuff is minimal now, it can be included. If and
when it ever grows to a substantial size, we can break it out.
> Here is the docstring for the texmanager module:
great -- that is very human readable in the src code, which is what I want.
> Ok, they are included now:
> http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
> and http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf
Het, now we are getting somewhere! We may need to work on the toc a
bit, since we should see one header for "The Artist Tutorial" and then
all the subheaders indented relative to that, but that should be easy
enough. There is also some code formatting problem in the PDF -- see
the 'import numpy as np" in the "Style Guide" section of the PDF.
JDH

On Thursday 22 May 2008 02:05:14 pm John Hunter wrote:
> On Thu, May 22, 2008 at 12:48 PM, Darren Dale <dar...@co...> 
wrote:
> > You're right, that sounds easier. Here's a taste, it has a bit taken from
> > the users guide, I marked up the CODING_GUIDE, and I used the autodoc
> > extension to document the API of texmanager and dviread:
>
> How do you envision putting this together? Will each of these
> documents (eg CODING_GUIDE) live as separate rest files and are then
> included in one doc? 
We have a lot of flexibility here. I prefer to pull from a few smaller 
documents using rest include statements or table of contents directives. 
Ipython, on the other hand, has the whole guide included in one file.
> I don't think we will want to have one master 
> PDF for the user's guide, developer's guide and api docs (the
> autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
> pages along).
Ok. It is easy enough to break them up into separate documents. I'll work on 
it this afternoon. Should we have a separate developers guide, or could it be 
included in the users guide?
> Did you do any rest conversion of the texmanager and 
> dviread, or did autodoc do everything? 
I had to do some minor modifications to make sure the docstrings were valid 
rest: proper indentation is important, and * is used to indicate emphasis, so 
any references to *args or **kwags had to be changed to ``*args`` and 
``**kwargs`` (I didnt like \*\*kwargs, its too intrusive for reading the 
plain text).
> I'd like to get a feel for 
> what the rest markup of the docstrings will look like.
Here is the docstring for the texmanager module:
"""
This module supports embedded TeX expressions in matplotlib via dvipng
and dvips for the raster and postscript backends. The tex and
dvipng/dvips information is cached in ~/.matplotlib/tex.cache for reuse 
between
sessions
Requirements:
* latex
* \*Agg backends: dvipng
* PS backend: latex w/ psfrag, dvips, and Ghostscript 8.51
 (older versions do not work properly)
Backends:
* \*Agg
* PS
* PDF
For raster output, you can get RGBA numpy arrays from TeX expressions
as follows::
 texmanager = TexManager()
 s = '\\TeX\\ is Number $\\displaystyle\\sum_{n=1}^\\infty\\frac{-e^{i\pi}}
{2^n}$!'
 Z = self.texmanager.get_rgba(s, size=12, dpi=80, rgb=(1,0,0))
To enable tex rendering of all text in your matplotlib figure, set
text.usetex in your matplotlibrc file (http://matplotlib.sf.net/matplotlibrc)
or include these two lines in your script::
 from matplotlib import rc
 rc('text', usetex=True)
"""
I am really amazed at how much can be done with so little. For example, near 
the end of that docstring, two colons followed by a blank line and then an 
indented block indicates a block of source code. 
> In any case, this is exciting, since I am eager to have a nice rest
> based doc system. You might want to look at incorporating the three
> rest docs in the doc subdir: artist_api_tut.txt,
> event_handling_tut.txt and devel/add_new_projection.rst since these
> are already done.
Ok, they are included now:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
and http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf
> I guess we also need to standardize on rst vs txt 
> extensions. I think txt is friendlier to windoze users, and I have my
> emacs to use rest mode for *.txt
> (require 'rst)
> (autoload 'rst-mode "rst-mode" "mode for editing reStructuredText
> documents" t) (setq auto-mode-alist
> (append '(
> 		 ("\\.txt$" . rst-mode)
> 		 ("\\.rst$" . rst-mode)
> 		 ("\\.rest$" . rst-mode)) auto-mode-alist))
I prefer .rst, it makes it clear that there is a specific markup, which could 
be overlooked by the uninitiated contributer. But I don't have a strong 
opinion.
> As you as you can, commit a working directory for the doc build and
> I'll help with some of the conversion of the existing docs to rest.
> We can split up the user's guide chapters, etc...
Sounds good. I'll work on splitting the docs and make the commit this 
afternoon. Before I commit, could we have a ruling on whether the developers 
guide should be included in the users guide, and should we use .rst or .txt 
extensions? (sphinx wants one or the other.)
Darren

On Thu, May 22, 2008 at 12:48 PM, Darren Dale <dar...@co...> wrote:
> You're right, that sounds easier. Here's a taste, it has a bit taken from the
> users guide, I marked up the CODING_GUIDE, and I used the autodoc extension
> to document the API of texmanager and dviread:
How do you envision putting this together? Will each of these
documents (eg CODING_GUIDE) live as separate rest files and are then
included in one doc? I don't think we will want to have one master
PDF for the user's guide, developer's guide and api docs (the
autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
pages along). Did you do any rest conversion of the texmanager and
dviread, or did autodoc do everything? I'd like to get a feel for
what the rest markup of the docstrings will look like.
In any case, this is exciting, since I am eager to have a nice rest
based doc system. You might want to look at incorporating the three
rest docs in the doc subdir: artist_api_tut.txt,
event_handling_tut.txt and devel/add_new_projection.rst since these
are already done. I guess we also need to standardize on rst vs txt
extensions. I think txt is friendlier to windoze users, and I have my
emacs to use rest mode for *.txt
(require 'rst)
(autoload 'rst-mode "rst-mode" "mode for editing reStructuredText documents" t)
(setq auto-mode-alist
 (append '(
		 ("\\.txt$" . rst-mode)
		 ("\\.rst$" . rst-mode)
		 ("\\.rest$" . rst-mode)) auto-mode-alist))
As you as you can, commit a working directory for the doc build and
I'll help with some of the conversion of the existing docs to rest.
We can split up the user's guide chapters, etc...
JDH

On Thursday 22 May 2008 01:23:53 pm Michael Droettboom wrote:
> Just something to keep in mind: many of the docstrings are pieced
> together at import time (to avoid rewriting descriptions of common
> parameters). Any tool that extracts docstrings by parsing Python rather
> than importing Python may choke on that approach.
Yes, that might have been a big problem, but it looks like Sphinx does the 
right thing. axes.Axes.plot includes the following in its docstring:
 The kwargs are Line2D properties:
 %(Line2D)s
And the rendering at 
http://dale.chess.cornell.edu/~darren/temp/matplotlib/mpl_api.xml#matplotlib-axes
is what we would want (although the formatting in html is missing some 
newlines):
The kwargs are Line2D properties:
 alpha: float
 animated: [True | False]
 antialiased or aa: [True | False]
 axes: unknown
 clip_box: a matplotlib.transform.Bbox instance
 clip_on: [True | False]
 clip_path: a Path instance and a Transform instance, a Patch
 color or c: any matplotlib color
 contains: unknown
 dash_capstyle: [‘butt’ | ‘round’ | ‘projecting’]
 dash_joinstyle: [‘miter’ | ‘round’ | ‘bevel’]
 dashes: sequence of on/off ink in points
 data: (np.array xdata, np.array ydata)
 figure: a matplotlib.figure.Figure instance
 label: any string
 linestyle or ls: 
[ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ | ‘None’ | ‘ ‘ | ‘’ ]
 linewidth or lw: float value in points
 lod: [True | False]
 marker: [ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’
 markeredgecolor or mec: any matplotlib color
 markeredgewidth or mew: float value in points
 markerfacecolor or mfc: any matplotlib color
 markersize or ms: float
 picker: unknown
 pickradius: unknown
 solid_capstyle: [‘butt’ | ‘round’ | ‘projecting’]
 solid_joinstyle: [‘miter’ | ‘round’ | ‘bevel’]
 transform: a matplotlib.transforms.Transform instance
 visible: [True | False]
 xdata: np.array
 ydata: np.array
 zorder: any number

Joh...@in... wrote:
> Hi Eric,
> 
> This goes back a bit, but did you get any resolution to the fading problem?
> I'm having the same problem at the moment, with the latest versions of 
> matplotlib using wxagg on windows.
> 
> Thanks
> John
> 
> 
> 
John,
http://www.mail-archive.com/mat...@li.../msg00513.html
I'm not sure whether this is different in the trunk now. By "latest 
versions" do you mean svn trunk, or 0.91.2?
I just tried testing with
imshow(rand(2,2))
followed by multiple zoom-to-rect operations, and I am not seeing the 
fade-out, but I am seeing the CPU tied up for 10s of seconds. In fact, 
I can get this with only one or two zooms.
Eric

On Thursday 22 May 2008 09:56:04 am John Hunter wrote:
> On Thu, May 22, 2008 at 8:15 AM, Darren Dale <dar...@co...> 
wrote:
> > I am planning on starting to overhaul the documentation using Sphinx next
> > week. I have been experimenting with Sphinx to create some documentation
> > for a project at work
> > (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
> > http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really
> > impressed with Sphinx, I think it will allow us to unify the matplotlib
> > docstrings, webpage and the pdf copies of the users guide / developers
> > guide / API reference.
>
> These look nice.
>
> > In order to integrate all the doumentation together, it would be best if
> > I could convert the mpl docstrings to ReST. This would be quite a big
> > project, and I don't want to commit us before we have a chance to
> > evaluate the results, so I guess a documentation branch would be
> > appropriate. Could someone help guide me through the process of creating
> > a new branch and pulling in some of the older doc sources? Aside from
> > Johns recent post about using svnmerge, is there anything else I should
> > keep in mind while trying to keep the branch in sync with the trunk?
>
> I'd rather avoid another branch if possible. I think it would be
> easier to just do a single module first and post it to the list, and
> then we can evaluate it. If we like it, then we can just keep doing a
> module at a time in the trunk.
You're right, that sounds easier. Here's a taste, it has a bit taken from the 
users guide, I marked up the CODING_GUIDE, and I used the autodoc extension 
to document the API of texmanager and dviread:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf
For comparison, here is the texmanager API done with Sphinx:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/mpl_api.xml#module-matplotlib.texmanager
and here is the existing API documentation:
http://matplotlib.sourceforge.net/matplotlib.texmanager.html
Darren

I haven't initialized it for that direction. In a lot of ways, svnmerge 
is far less useful in that case because there are many more things going 
on the trunk that you don't want in the branch than vice versa.
I think in this case, a vanilla 'svn merge' (i.e. not using svnmerge.py) 
is probably going to be easier.
See here http://svnbook.red-bean.com/en/1.4/svn.branchmerge.copychanges.html
Cheers,
Mike
John Hunter wrote:
> On Sat, May 17, 2008 at 4:40 PM, John Hunter <jd...@gm...> wrote:
>
> 
>> - Michael advises making the change on the branch and committing
>> it. Make sure you svn upped on the trunk and have no local
>> modifications, and then from the svn trunk do
>> 
>
> ichael -- what if someone has already made a change on the trunk and
> wants to merge it to the branch with svnmerge? What is the
> recommended way to do this? Can they simply go to the branch and do
> 'svnmerge.py merge'?
>
> JDH
>
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 

Just something to keep in mind: many of the docstrings are pieced 
together at import time (to avoid rewriting descriptions of common 
parameters). Any tool that extracts docstrings by parsing Python rather 
than importing Python may choke on that approach.
Cheers,
Mike

On Sat, May 17, 2008 at 4:40 PM, John Hunter <jd...@gm...> wrote:
> - Michael advises making the change on the branch and committing
> it. Make sure you svn upped on the trunk and have no local
> modifications, and then from the svn trunk do
ichael -- what if someone has already made a change on the trunk and
wants to merge it to the branch with svnmerge? What is the
recommended way to do this? Can they simply go to the branch and do
'svnmerge.py merge'?
JDH

Thanks, John. Here is the patch for the v0_91_maint branch. As far as I
can tell, analogous changes can be made to the trunk.
Also, I believe that this resolves bug 1287318 for the WX* backends.

On Thu, May 22, 2008 at 8:15 AM, Darren Dale <dar...@co...> wrote:
> I am planning on starting to overhaul the documentation using Sphinx next
> week. I have been experimenting with Sphinx to create some documentation for
> a project at work (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
> http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really impressed
> with Sphinx, I think it will allow us to unify the matplotlib docstrings,
> webpage and the pdf copies of the users guide / developers guide / API
> reference.
These look nice.
> In order to integrate all the doumentation together, it would be best if I
> could convert the mpl docstrings to ReST. This would be quite a big project,
> and I don't want to commit us before we have a chance to evaluate the
> results, so I guess a documentation branch would be appropriate. Could
> someone help guide me through the process of creating a new branch and
> pulling in some of the older doc sources? Aside from Johns recent post about
> using svnmerge, is there anything else I should keep in mind while trying to
> keep the branch in sync with the trunk?
I'd rather avoid another branch if possible. I think it would be
easier to just do a single module first and post it to the list, and
then we can evaluate it. If we like it, then we can just keep doing a
module at a time in the trunk.

I am planning on starting to overhaul the documentation using Sphinx next 
week. I have been experimenting with Sphinx to create some documentation for 
a project at work (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and 
http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really impressed 
with Sphinx, I think it will allow us to unify the matplotlib docstrings, 
webpage and the pdf copies of the users guide / developers guide / API 
reference.
In order to integrate all the doumentation together, it would be best if I 
could convert the mpl docstrings to ReST. This would be quite a big project, 
and I don't want to commit us before we have a chance to evaluate the 
results, so I guess a documentation branch would be appropriate. Could 
someone help guide me through the process of creating a new branch and 
pulling in some of the older doc sources? Aside from Johns recent post about 
using svnmerge, is there anything else I should keep in mind while trying to 
keep the branch in sync with the trunk?
Thanks,
Darren

On Tuesday 25 March 2008 07:07:33 pm Gael Varoquaux wrote:
> On Tue, Mar 25, 2008 at 06:04:41PM -0500, bryce hendrix wrote:
> > How stable is the API? We (Enthought) use endo, a custom tool build on
> > top of docutils, to generate our docs currently. We have talked about
> > changing tools in the past, but the need to extend the tools to
> > understand Traits has held us back.
>
> Sphinx is not automated API documentation, like Endo or Epidoc. It is for
> manual writing of documentation. It does not compete with Endo or Epidoc,
> but complements them by taking a set of rst files and compiling both a
> set of searchable web pages, and an indexed pdf for print.
Well, I have read that elsewhere, maybe even on the sphinx website, but you 
actually can use it to document the API. I haven't done a complete comparison 
of epydoc and sphinx's autodoc extension, but their output seems pretty 
comparable.
Darren