Re: [matplotlib-devel] future of mpl documentation
On Monday 02 June 2008 08:33:55 Michael Droettboom wrote:
Darren Dale wrote:
On Saturday 31 May 2008 11:44:34 pm Darren Dale wrote:
On Saturday 31 May 2008 10:19:47 pm John Hunter wrote:
On Sat, May 31, 2008 at 9:01 PM, Fernando Perez [EMAIL PROTECTED]
I tracked this down by checking the contents of the generated
build/latex/Matplotlib.tex, line 954. It is from the following code from
mathtext.rst:
When using the STIX fonts, you also have the choice of:
=
Command Result
=
``\mathbb`` :math:`\mathbb{Blackboard}`
``\mathcircled`` :math:`\mathcircled{Circled}`
``\mathfrak``:math:`\mathfrak{Fraktur}`
``\mathsf`` :math:`\mathsf{sans-serif}`
=
I'm not sure this is being properly rendered in the HTML output for me,
either. Mike, are you able to compile this into a pdf on your machine,
and if so, would you tell us how to configure STIX support? I commented
this block out in svn for now.
Sorry about that. It requires the amssymb and/or amsmath LaTeX packages
to render correctly. Perhaps it is better to not require the LaTeX
installation to have anything special though. I think the best course
of action is to just include pre-generated images in the documentation
source for this. I'll go ahead and do that.
I added doc/static_figs to hold scripts that require optional dependencies to
generate images for the docs. I would like to be able to keep track of how the
images are generated, so if we lose one we know how to recreate it. I added
two scripts (softlinks actually) a README and a make.py to that directory.
make.py saves the images to doc/_static.
-
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Monday 02 June 2008 09:12:45 Michael Droettboom wrote: John Hunter wrote: On Sat, May 31, 2008 at 9:19 AM, Darren Dale [EMAIL PROTECTED] wrote: I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. The only reason to do them on the branch too is to make merges of other code changes easier, which may be a compelling reason. If the docstrings get far out of whack, it may make merging other changes very painful. But at the same time, I don't want the burden of trying to keep the two in sync stopping you from getting the work done that you need to do. Maybe you can try it and see how hard it is, and if proves to be too much of an impediment, just concentrate on the trunk. Michael, any advice here? I was away on the weekend, so just getting back. Darren: you rock. The documentation is looking great! I agree, the documentation is coming along nicely. But I don't think I should be singled out for credit, there's lots of good stuff appearing that I haven't had anything to do with. - Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://sourceforge.net/services/buy/index.php ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Hi all
I only read this thread today, and see that we have been battling many
of the same challenges in our documentation efforts. I am glad to see
that you are making such good progress!
2008/6/1 John Hunter [EMAIL PROTECTED]:
I just realized, though, that I should probably be striving to conform with
the standard that the numpy and scipy folks put together:
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and
http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I
think I have been relying too heavily on tables for the keyword arguments.
I think that following their guidelines is a good idea for the most
part, but we needn't adhere to them religiously. For one thing,
matplotlib uses *a lot* more keyword args than either numpy or scipy,
and what works for them for kwargs may not be best for us. In
particular, if we use the format they suggest, I'm afraid our
docstrings will simply take up too much space. For example, see
http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-none
. What if we formatted all the Line2d kwargs that way? It seems a
bit bloated in terms of vertical space for the number of kwargs we
need to handle, and so a ReST table may in fact be better.
I'd like to explain the rationale behind our approach. Our main focus
was to write produce documentation that is easy to read from a
text-based terminal. While designing our standard, we set aside all
other concerns, such as markup, compatibility with existing tools,
etc. After the standard was more-or-less finalised, we wrote a tool
which parses docstrings into logical units. For example,
In [5]: d = SphinxFunctionDoc(np.ravel)
In [6]: d['Parameters']
Out[6]:
[('a', '{array_like}', ['']),
('order',
{'C','F'}, optional,
[If order is 'C' the elements are taken in row major order. If order,
is 'F' they are taken in column major order.])]
In [7]: print d
**ravel(a, order='C')**
---
Return a 1d array containing the elements of a (copy only if needed).
[...]
Note that, when printing the docstring, it looks entirely different
from the original docstring, and contains customised markup. If you
wanted to use a table to describe keyword arguments, for example, it
would require only a few extra lines of code.
If you are interested in playing with the code, it is available at
https://code.launchpad.net/~stefanv/scipy/numpy-refguide
We also developed a web-framework that allows our community to write
documentation:
http://sd-2116.dedibox.fr/pydocweb
While it was written with NumPy in mind (we have some weird docstring
injection, not unlike yours), it should be trivial to modify for use
by another project.
Good luck!
Stéfan
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Darren Dale wrote:
On Saturday 31 May 2008 11:44:34 pm Darren Dale wrote:
On Saturday 31 May 2008 10:19:47 pm John Hunter wrote:
On Sat, May 31, 2008 at 9:01 PM, Fernando Perez [EMAIL PROTECTED]
I tracked this down by checking the contents of the generated
build/latex/Matplotlib.tex, line 954. It is from the following code from
mathtext.rst:
When using the STIX fonts, you also have the choice of:
=
Command Result
=
``\mathbb`` :math:`\mathbb{Blackboard}`
``\mathcircled`` :math:`\mathcircled{Circled}`
``\mathfrak``:math:`\mathfrak{Fraktur}`
``\mathsf`` :math:`\mathsf{sans-serif}`
=
I'm not sure this is being properly rendered in the HTML output for me,
either. Mike, are you able to compile this into a pdf on your machine, and if
so, would you tell us how to configure STIX support? I commented this block
out in svn for now.
Sorry about that. It requires the amssymb and/or amsmath LaTeX packages
to render correctly. Perhaps it is better to not require the LaTeX
installation to have anything special though. I think the best course
of action is to just include pre-generated images in the documentation
source for this. I'll go ahead and do that.
Cheers,
Mike
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
John Hunter wrote: On Sat, May 31, 2008 at 9:19 AM, Darren Dale [EMAIL PROTECTED] wrote: I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. The only reason to do them on the branch too is to make merges of other code changes easier, which may be a compelling reason. If the docstrings get far out of whack, it may make merging other changes very painful. But at the same time, I don't want the burden of trying to keep the two in sync stopping you from getting the work done that you need to do. Maybe you can try it and see how hard it is, and if proves to be too much of an impediment, just concentrate on the trunk. Michael, any advice here? I was away on the weekend, so just getting back. Darren: you rock. The documentation is looking great! I agree with John -- I think the documentation effort should be focused on the trunk. Now that we have (apparently) such a stable 0.91.3, hopefully the maintenance branch will be much less frequently modified anyway. Theoretically, we should only run into merge conflicts related to docstrings if the docstrings on the maintenance branch are themselves edited. If we're just going to be doing bugfixes on the branch, that seems unlikely. Cheers, Mike -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Saturday 31 May 2008 11:44:34 pm Darren Dale wrote:
On Saturday 31 May 2008 10:19:47 pm John Hunter wrote:
On Sat, May 31, 2008 at 9:01 PM, Fernando Perez [EMAIL PROTECTED]
wrote:
I don't know if you are so in the middle of things that you'd rather
not get bug reports on this for a while. If that's the case I'll wait
until the dust settles a bit.
Well, we definitely want our docs to build so we're happy to get the
feedback -- sometimes it's a simple matter of a dev forgetting to
commit a critical file. I am getting this error too. It appears to
be a bug in the pyplot docstrings -- Darren, perhaps you haven't
committed all you recent changes?
All my changes had already been committed. I had only been creating html
(./make.py html) and it looks like some of the tables I have been creating
dont agree with latex. I'll fix it tomorrow, but in the meantime, please
just make html.
Alright, I've tracked down the source of these two errors. Sphinx can not
create tables in latex that have cells spanning multiple rows or multiple
columns. Maybe it is a limitation of latex, I'm not sure, I don't have my
latex books handy. But it looks like tables with row- or column-spanning
cells are henceforth verboten.
I've updated pyplot_api.rst in svn so it is basically empty and will not cause
anyone trouble while I fix the broken tables.
But if I remove entirely the pyplot
api doc which is causing this problem, I get lots of other errors
along the lines of those shown below. Is this a latex or sphinxext
config error?
[8 ./pyplot_formatstr.png ./pyplot_three.png] [9] [10]
pyplot_two_subplots.png, id=368, 578.16pt x 433.62pt
use pyplot_two_subplots.png use pyplot_two_subplots.png [11
./pyplot_two_s ubplots.png] pyplot_text.png, id=375, 578.16pt x
433.62pt
use pyplot_text.png use pyplot_text.png [12 ./pyplot_text.png] [13]
[14]
Chapter 2.
[15] [16]
! Undefined control sequence.
recently read \mathbb
l.954 \end{tabulary}
I tracked this down by checking the contents of the generated
build/latex/Matplotlib.tex, line 954. It is from the following code from
mathtext.rst:
When using the STIX fonts, you also have the choice of:
=
Command Result
=
``\mathbb`` :math:`\mathbb{Blackboard}`
``\mathcircled`` :math:`\mathcircled{Circled}`
``\mathfrak``:math:`\mathfrak{Fraktur}`
``\mathsf`` :math:`\mathsf{sans-serif}`
=
I'm not sure this is being properly rendered in the HTML output for me,
either. Mike, are you able to compile this into a pdf on your machine, and if
so, would you tell us how to configure STIX support? I commented this block
out in svn for now.
Cheers,
Darren
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Sunday 01 June 2008 12:53:48 am John Hunter wrote: On Sat, May 31, 2008 at 11:27 PM, Tony Yu [EMAIL PROTECTED] wrote: I like the new color scheme on the website. Since you asked for criticism, though, I'm not a fan of the blue matplotlib in the logo (on the website, the attached logo is actually different). I think black or a dark gray looks better (color=[0.2, 0.2, 0.2]). Or, if you prefer blue, something less like the default hyperlink color (e.g. color=[.1,.1,.5]). My 2 cents. I agree -- I had already reverted to black (hit refresh). But if you think some other shade of dark gray or blue/gray is better let me know. Speaking as a recovering graphical design major and insensitive curmudgeon... it looks great, nice work! I do have two comments though: the 90 and 270 ticklabels are cut off, and I think the plot would look a little cleaner if the ticklabel pad were increased so the radial ticks were a little further from the axes. BTW, I noticed that website is a little old (pure HTML, no CSS). If you're ever interested in redesigning the website (nothing fancy, mainly just moving to CSS), I'd be happy to help out. We're definitely interested. Try checking out the htdocs svn repository. Admittedly we do things in our own special way (eg the YAPTU template engine), but if we could improve the look-and-feel that would be great. None of us have any special powers in the website-design department. Even better, as part of our new trunk documentation effort, we have moved to a sphinx based documentation system (in the doc subdir of svn trunk). If you could figure out a way to hook custom CSSandr mpl figures/screenshots or any other snazzy features into the base sphinx build system, that would be a big help since we hope to jettison the somewhat anachronistic website build system n the not-too-distant-future. I was intending to write the list and ask if anyone was interested in playing with CSS to customize the looks of the new sphinx-based documentation effort. I'm really happy to hear that you're interested in helping out, Tony. I second Johns suggestion of having a look at the doc/ directory in the trunk, and getting familiar with sphinx. I think most of the content on the website is going to find a new home in the sphinx-based docs, and it would be nice if the front page, sidebars, etc could also be generated with sphinx. For the moment, you can build the html documentation by running make.py html in the doc directory. The latex-pdf docs are experiencing growing pains, I'll work on it this morning. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Saturday 31 May 2008 10:45:34 pm John Hunter wrote: On Sat, May 31, 2008 at 7:50 PM, Darren Dale [EMAIL PROTECTED] wrote: I just realized, though, that I should probably be striving to conform with the standard that the numpy and scipy folks put together: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I think I have been relying too heavily on tables for the keyword arguments. I think that following their guidelines is a good idea for the most part, but we needn't adhere to them religiously. For one thing, matplotlib uses *a lot* more keyword args than either numpy or scipy, and what works for them for kwargs may not be best for us. In particular, if we use the format they suggest, I'm afraid our docstrings will simply take up too much space. For example, see http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-non e . What if we formatted all the Line2d kwargs that way? It seems a bit bloated in terms of vertical space for the number of kwargs we need to handle, and so a ReST table may in fact be better. I agree. We should default to parameter lists, but longer lists of kwargs will be formatted as tables. There are also some features in the numpy template (like the use of sections) that cause sphinx to fail. I wonder how the webpage you referenced was generated? We want our documentation to be mostly consistent to aid the folks trying to put together bits and pieces of documentation from several projects to write in-house docs (which incorporate local docs) or books, but I'm not sure we need our doc formatting to be entirely consistent at the API level. Right, we shouldn't worry about rigorously adhering to a standard, but their template seems like a good guideline to keep in mind. - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Jun 1, 2008, at 4:30 AM, John Hunter wrote: Let me know what you think... Generally, I like the logo, and think it is a *huge* improvement on the old one. Two suggestions: 1. The original new logo was done in a Helvetica medium font, which is much nicer for this type of logo. (See the Helvetica movie, and become a true believer...). 2. I like the figure to the side (and agree that there should be only one), but it seems that polar plots are more rarely used than normal x- y plots. Perhaps an x-y plot (the histogram, for example) would be better advertising. -Rob Rob Hetland, Associate Professor Dept. of Oceanography, Texas AM University http://pong.tamu.edu/~rob phone: 979-458-0096, fax: 979-845-6331 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Jun 1, 2008, at 6:00 AM, Darren Dale wrote: On Sunday 01 June 2008 12:53:48 am John Hunter wrote: We're definitely interested. Try checking out the htdocs svn repository. Hmm, the README file says I need all the backends working. I don't think I want to try that on my Mac. I'll try it out with a linux machine I have in lab. Admittedly we do things in our own special way (eg the YAPTU template engine), but if we could improve the look-and-feel that would be great. None of us have any special powers in the website-design department. Even better, as part of our new trunk documentation effort, we have moved to a sphinx based documentation system (in the doc subdir of svn trunk). If you could figure out a way to hook custom CSSandr mpl figures/screenshots or any other snazzy features into the base sphinx build system, that would be a big help since we hope to jettison the somewhat anachronistic website build system n the not-too-distant-future. I was intending to write the list and ask if anyone was interested in playing with CSS to customize the looks of the new sphinx-based documentation effort. I'm really happy to hear that you're interested in helping out, Tony. Actually, I really like the default look of sphinx-based docs, but I wouldn't mind playing around with it. What did you have in mind? For the moment, you can build the html documentation by running make.py html in the doc directory. The latex-pdf docs are experiencing growing pains, I'll work on it this morning. html built fine on my machine; it looks really nice. The pdf docs also built without problems. Nice work. -Tony - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Sunday 01 June 2008 10:23:47 am Tony Yu wrote: On Jun 1, 2008, at 6:00 AM, Darren Dale wrote: I was intending to write the list and ask if anyone was interested in playing with CSS to customize the looks of the new sphinx-based documentation effort. I'm really happy to hear that you're interested in helping out, Tony. Actually, I really like the default look of sphinx-based docs, but I wouldn't mind playing around with it. What did you have in mind? Our front page has various sidebars that include announcements, links to the sourceforge download page, etc. I like the default look of sphinx-based html as well, but I also like the look of the moin-based scipy page. For the moment, you can build the html documentation by running make.py html in the doc directory. The latex-pdf docs are experiencing growing pains, I'll work on it this morning. html built fine on my machine; it looks really nice. The pdf docs also built without problems. Nice work. Yes, pdf is working again, I sorted out the issues that John and Fernando reported last night. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
I'm not sure either, it was something simple like having problems building and John suggesting that I blow away the previous installation. But I indeed did eventually mail the doughnut. Perry On May 31, 2008, at 10:35 PM, John Hunter wrote: On Sat, May 31, 2008 at 3:19 PM, Darren Dale [EMAIL PROTECTED] wrote: Darren I have to break here for the weekend, I'll be back monday afternoon. Darren Leave some for me! (although I'll owe doughnut to whoever can fix the Darren arrow docstring). John I'll claim that doughnut. Darren When was the last time you received one in the mail? Well, I remember the last time quite clearly, when Perry sent me a doughnut in the mail from Maryland to settle a dollars-to doughnuts bet. Unfortunately, I can't remember the subject of the bet right now (Perry?), though I kept the doughnut in my freezer, in the addressed envelope, for many months as a souvenir. JDH - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Jun 1, 2008, at 9:47 AM, Rob Hetland wrote: 2. I like the figure to the side (and agree that there should be only one), but it seems that polar plots are more rarely used than normal x-y plots. Perhaps an x-y plot (the histogram, for example) would be better advertising. I was the one who originally chose the polar plot. I admit, it was mainly for aesthetics. Here are a few reasons: * I think a circular plot works better on the logo than a rectangular plot would. * The polar plot is one of the more attractive plots in the examples. * It's a plotting featuring that most plotting software wouldn't have so it seems to differentiate matplotlib from other plotting software. Originally, it wasn't a big deal because there were other plots in the logo. Still, I'd be in favor of keeping the polar plot for aesthetic reasons. Great, now I'm that guy who's arguing for looks over practicality. :( -Tony - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Sat, May 31, 2008 at 9:19 AM, Darren Dale [EMAIL PROTECTED] wrote: I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. The only reason to do them on the branch too is to make merges of other code changes easier, which may be a compelling reason. If the docstrings get far out of whack, it may make merging other changes very painful. But at the same time, I don't want the burden of trying to keep the two in sync stopping you from getting the work done that you need to do. Maybe you can try it and see how hard it is, and if proves to be too much of an impediment, just concentrate on the trunk. Michael, any advice here? JDH - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Saturday 31 May 2008 12:36:11 pm John Hunter wrote: On Sat, May 31, 2008 at 9:19 AM, Darren Dale [EMAIL PROTECTED] wrote: I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. I would really prefer to concentrate on the trunk. There's enough work as it is. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Saturday 31 May 2008 4:14:39 pm Darren Dale wrote: On Saturday 31 May 2008 12:36:11 pm John Hunter wrote: On Sat, May 31, 2008 at 9:19 AM, Darren Dale [EMAIL PROTECTED] wrote: I'll be working on converting docstrings to rest this weekend. Should any of this be done on the branch? Or should we just focus on the trunk? As far as I am concerned, the documentation effort is for the trunk. I would really prefer to concentrate on the trunk. There's enough work as it is. I made some pretty good progress today. I found the source of that error that was causing sphinx to fail without a helpfull message, there was a * in the contour documentation. pyplot_api is about halfway converted, there are only 60 warnings reported by sphinx for pyplot. I just realized, though, that I should probably be striving to conform with the standard that the numpy and scipy folks put together: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I think I have been relying too heavily on tables for the keyword arguments. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Hey folks,
I'm super excited about this, so I decided to give it a quick test run
with current trunk SVN. Running ./make.py in the doc/ directory
worked for a while, and then stalled at:
Sphinx v0.3, building latex
trying to load pickled env... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
processing Matplotlib.tex... index users/index users/pyplot_tutorial
users/mathtext users/navigation_toolbar users/customizing
users/artists users/event_handling faq/index faq/installing_faq
faq/troubleshooting_faq faq/howto_faq devel/index devel/coding_guide
devel/documenting_mpl devel/add_new_projection api/index
api/artist_api api/pyplot_api
resolving references...
writing... Exception occurred:
File
/home/fperez/usr/local/lib/python2.5/site-packages/Sphinx-0.3-py2.5.egg/sphinx/latexwriter.py,
line 479, in visit_entry
raise NotImplementedError('Column or row spanning cells are '
NotImplementedError: Column or row spanning cells are not implemented.
The full traceback has been saved in /tmp/sphinx-err-l_Oadi.log, if
you want to report the issue to the author.
Please also report this if it was a user error, so that a better error
message can be provided next time.
Send reports to [EMAIL PROTECTED] Thanks!
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
%-line parsing enabled.
entering extended mode
! I can't find file `Matplotlib.tex'.
* Matplotlib.tex
Please type another input file name:
I don't know if you are so in the middle of things that you'd rather
not get bug reports on this for a while. If that's the case I'll wait
until the dust settles a bit.
In any case, many thanks for pushing this doc effort forward! The
overall usability of the combined tools, in a few months, is going to
really be massively improved thanks to all this common focus on
sphinx-based docs.
Cheers,
f
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Mon, May 26, 2008 at 1:50 PM, Tony Yu [EMAIL PROTECTED] wrote: I played around with the script, but in the process I ended up rewriting it a bunch. I'm sure I've violated come coding guidelines along the way; my apologies. And I made several changes -- mainly to simplify the logo. My wife thought it looked busy, and she has better taste than I do, so I stripped it down a bunch and added the many small subplots as a sidebar on the right. Let me know what you think and don't be shy about being critical despite Darren's kind sensitivities. I don't take pride in my graphic design abilities and so will happily make changes See http://matplotlib.sf.net for the new logo(s) and the attached for the stripped down script. JDH attachment: logo2.png- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Sat, May 31, 2008 at 9:01 PM, Fernando Perez [EMAIL PROTECTED] wrote:
I don't know if you are so in the middle of things that you'd rather
not get bug reports on this for a while. If that's the case I'll wait
until the dust settles a bit.
Well, we definitely want our docs to build so we're happy to get the
feedback -- sometimes it's a simple matter of a dev forgetting to
commit a critical file. I am getting this error too. It appears to
be a bug in the pyplot docstrings -- Darren, perhaps you haven't
committed all you recent changes? But if I remove entirely the pyplot
api doc which is causing this problem, I get lots of other errors
along the lines of those shown below. Is this a latex or sphinxext
config error?
[8 ./pyplot_formatstr.png ./pyplot_three.png] [9] [10]
pyplot_two_subplots.png, id=368, 578.16pt x 433.62pt
use pyplot_two_subplots.png use pyplot_two_subplots.png [11 ./pyplot_two_s
ubplots.png] pyplot_text.png, id=375, 578.16pt x 433.62pt
use pyplot_text.png use pyplot_text.png [12 ./pyplot_text.png] [13]
[14]
Chapter 2.
[15] [16]
! Undefined control sequence.
recently read \mathbb
l.954 \end{tabulary}
?
! Undefined control sequence.
recently read \mathcircled
l.954 \end{tabulary}
...and lots more like this
JDH
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Sat, May 31, 2008 at 11:27 PM, Tony Yu [EMAIL PROTECTED] wrote: I like the new color scheme on the website. Since you asked for criticism, though, I'm not a fan of the blue matplotlib in the logo (on the website, the attached logo is actually different). I think black or a dark gray looks better (color=[0.2, 0.2, 0.2]). Or, if you prefer blue, something less like the default hyperlink color (e.g. color=[.1,.1,.5]). My 2 cents. I agree -- I had already reverted to black (hit refresh). But if you think some other shade of dark gray or blue/gray is better let me know. BTW, I noticed that website is a little old (pure HTML, no CSS). If you're ever interested in redesigning the website (nothing fancy, mainly just moving to CSS), I'd be happy to help out. We're definitely interested. Try checking out the htdocs svn repository. Admittedly we do things in our own special way (eg the YAPTU template engine), but if we could improve the look-and-feel that would be great. None of us have any special powers in the website-design department. Even better, as part of our new trunk documentation effort, we have moved to a sphinx based documentation system (in the doc subdir of svn trunk). If you could figure out a way to hook custom CSSandr mpl figures/screenshots or any other snazzy features into the base sphinx build system, that would be a big help since we hope to jettison the somewhat anachronistic website build system n the not-too-distant-future. JDH - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
My 2 cents: I think it looks better if you reduce the number of histogram bins from 50 down to 15 or 20. Gary R. John Hunter wrote: I played around with this a bit this morning -- it may be too busy for your OS X sensibilities, but let me know if you think think this is an approach wotrh pursuing. I've added the mathtext background and a few axes and there are a few more axes to do. In svn as examples/api/logo2.py - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On May 25, 2008, at 12:13 PM, John Hunter wrote: I played around with this a bit this morning -- it may be too busy for your OS X sensibilities, but let me know if you think think this is an approach wotrh pursuing. I've added the mathtext background and a few axes and there are a few more axes to do. In svn as examples/api/logo2.py I must admit, I was a little worried when you suggested adding a big equation in the background, but I think you did a good job of making it look nice. Unfortunately, I get an error when I try to run the logo2 script: AttributeError: 'NoneType' object has no attribute 'get_ticklabels' module body in logo2.py at line 23 for label in ax.get_xticklabels() + ax.get_yticklabels(): If I comment-out that for-block, I run into another error: NotImplementedError: xlim not meaningful for polar axes module body in logo2.py at line 43 ax.set_xlim(-2*sigma, 2*sigma) I'm guessing the first error is a trunk vs. v0_91_maint issue? Is the second a naming error in the commit? Maybe axhist.set_xlim instead of ax.set_xlim? Overall I really like the new logo, but I'd like play around with it a bit for kicks. Thanks! -Tony- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote: On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle [EMAIL PROTECTED] wrote: It looks okay in Firefox 2.0.0.14 (though it did complain about missing the mathml fonts). IE 7 displays the xml tree. I don't mind using latex for math where is really helps but I think we should try to keep it to a minimum, since it appears mathml in the browsers is poorly supported. I also want to keep the docstrings as human readable as possible. I know that in some cases latex *adds* to the human readability, but in other cases it detracts, so we want to balance the elegance of the final pdflatex generated PDF output with the reality that many will be seeing the docs either in plain text or improperly rendered HTML. If it can be done easily enough with ascii math art, we should prefer that. Yes it is nice to keep things readable for the help system. One possibility is running the docstrings through a preprocessor as part of the install process. This can remove extraneous reST markup, and using tex2mail, convert latex formulae to ascii (I haven't tried it yet, but that's what it claims to do). This also lets you plug in attribute documentation at compile time rather than doing runtime hacks. However, the problem I was referring to above is that IE7 is not rendering the xml, even for pages which did not have mathml. This might be something simple like making sure files use .html rather than .xml. Darren has taken the temp pages down so I can't try that. - Paul - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Thursday 22 May 2008 10:10:13 pm John Hunter wrote: On Thu, May 22, 2008 at 4:59 PM, Darren Dale [EMAIL PROTECTED] wrote: 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*: Darren, thanks a lot for getting this going. I think this is going to push the documentation effort forward significantly. It certainly has got me hot and bothered to write some docs! A couple of organizational things: - flat is better than nested. I think the basic organization is good but I want to balance the cleanliness of the developer/build view with the plain text user view. To that end, perhaps having a source subdir in doc/users_guide is overkill. Should we have all the *.txt file live next to the make.py file? I want users browsing the doc/users_guide dir to see all the stuff they need (artist tut, event handling tut, etc) withought getting confused by the build or figures or data subdirs living beside a source subdir). It seems that it would not significantly add to the clutter to have all the txt files at a higher level. I just removed the source directories, like you suggested. You might get errors the next time you run make.py, just delete the build directories and it should correct itself. We *could* go one step further, and have all the *.txt files live directly in the doc dir itself, and the various subdirs like users_guide or api_reference or jpl or whatever could reference the parent directory for the includes. I'm not sure this is right, but it is consistent with the view that we have a lot of modular, somewhat freestanding, human readable, plain text rest files that can be combined into whatever package one wants via include files (eg the JPL could make their own custom docs from the pool) and it would work like the (old) pylab examples dir (one stop shopping for examples with ls and grep). Admittedly, the examples organization eventually became unwieldy, which is why I reorganized it in the trunk, but that is a good problem to have and it took years to get there. Your call, but just some food for thought. This way could work, but I think it would quickly become unwieldy. Lets stick with this for now, we can always reorganize later if we feel strongly about it. This way, JPL or others can still reference docs in their sister directories. - I think we should be mostly consistent with whether we use underscores to separate english words. So we have artist_api_tut .txt but userguide.txt. For the sake of a foolish consistency, how about user_guide.txt too? This is improved in the trunk. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Michael Droettboom wrote: Secondly, the ipython console sessions aren't getting syntax highlighted -- it would be nice if they did, particularly to indicate input vs. output. I'll volunteer to look into this -- I've done some pygments customization work in the past and maybe it won't be too difficult. I just committed support for this on the trunk. The usage is not automatic. The reST code must specifically request it using the ..sourcecode directive: .. sourcecode:: ipython In [101]: ax.lines[0] Out[101]: matplotlib.lines.Line2D instance at 0x19a95710 In [102]: line Out[102]: matplotlib.lines.Line2D instance at 0x19a95710 Making this automatic would have required monkey-patching Sphinx -- there doesn't seem to be an API to extend its algorithm to automatically select a syntax highlighter, as I suppose this requirement is somewhat obscure. Cheers, Mike -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Friday 23 May 2008 10:54:52 am John Hunter wrote: On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom [EMAIL PROTECTED] wrote: Personally, I would prefer to see all the names in monospaced type (I find it much more readable), but the additional markup may be somewhat at odds with keeping the original ReST source clean. There are also two roads to take: a) simply putting `` around them, or b) using the Sphinx cross-referencing constructs, e.g. :class:`Line2D`. b) is obviously a lot noisier in the original ReST, but could produce more useful online documentation. Note, however, that if we put the narrative and reference documentation in separate documents, the cross-references won't actually work between them. It certainly would make the docs more useful to be able to link to the class and function references. Argg. I guess I'll just have to give up my desire to have clean ASCII here, since most people are going to read this on the web or as PDF so we should target that. One question: suppose we use class:`Line2D` and include the reference docs in a single build, eg for the web site and a master PDF, but we want to provide on some occasions a lighter PDF, eg just a few of the docs w/o the reference. Will sphinx be somewhat smart and just format the class:`Line2D` as monospace when it cannot find the references? I just committed a few changes so equations can be rendered using the mathpng extension. The syntax is shown in the documenting_mpl.txt. - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Friday 23 May 2008 10:56:47 am Michael Droettboom wrote: Michael Droettboom wrote: Secondly, the ipython console sessions aren't getting syntax highlighted -- it would be nice if they did, particularly to indicate input vs. output. I'll volunteer to look into this -- I've done some pygments customization work in the past and maybe it won't be too difficult. I just committed support for this on the trunk. The usage is not automatic. The reST code must specifically request it using the ..sourcecode directive: .. sourcecode:: ipython In [101]: ax.lines[0] Out[101]: matplotlib.lines.Line2D instance at 0x19a95710 In [102]: line Out[102]: matplotlib.lines.Line2D instance at 0x19a95710 Making this automatic would have required monkey-patching Sphinx -- there doesn't seem to be an API to extend its algorithm to automatically select a syntax highlighter, as I suppose this requirement is somewhat obscure. I think it might be worth mentioning on Sphinx-dev, there might be some interest in supporting it. As it is, though, I don't think .. sourcecode:: ipython isn't much more distracting than, say: blah blah:: :ipython: In [101]: ax.lines[0] Out[101]: matplotlib.lines.Line2D instance at 0x19a95710 In [102]: line Out[102]: matplotlib.lines.Line2D instance at 0x19a95710 Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Friday 23 May 2008 03:02:55 pm John Hunter wrote: On Fri, May 23, 2008 at 9:54 AM, John Hunter [EMAIL PROTECTED] wrote: It certainly would make the docs more useful to be able to link to the class and function references. Argg. I guess I'll just have to give up my desire to have clean ASCII here, since most people are going to read this on the web or as PDF so we should target that. One question: suppose we use class:`Line2D` and include the reference docs in a single build, eg for the web site and a master PDF, but we want to provide on some occasions a lighter PDF, eg just a few of the docs w/o the reference. Will sphinx be somewhat smart and just format the class:`Line2D` as monospace when it cannot find the references? I've been experimenting with including the api docs in the same build to see if I could get linking to work, eg links in the pyplot tutorial to matplotlib.lines.Line2D. I know if we go this route some more reorganization will be needed, so we should figure that out and get our commits in and then freeze while Darren does the reorg. I was able to get the linking to work, as I posted in my last message, but forgot to address a reorg. I'm happy to do it, but I will be out of town and away from a computer Saturday morning through Monday afternoon. If we decide to include the api in the users guide (I think it is worth considering), I can do it when I get back. We can potentially pare back the size of the api reference, since we have some control over what is and is not included. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Friday 23 May 2008 04:34:11 pm John Hunter wrote: On Fri, May 23, 2008 at 3:31 PM, Darren Dale [EMAIL PROTECTED] wrote: commit yout customizing.txt? done. I just discovered l # The name of an image file (within the static path) to place at the top of # the sidebar. #html_logo = 'logo.png' so I have to get to work creating a new cool mpl figure for the logo. Our old banner is so 70s. I wasn't going to say it... but yeah. :) I think we need to set a policy on how we are going to handle code in docstrings. There are lots of places where indentation and asterisks are causing trouble. Should examples be codeblocks (::) or doctests ()? I think inlines should just be `` quoted, like: data are plotted as ``plot(lags, c, **kwargs)`` Here is an example from axes.Axes: def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, maxlags=None, **kwargs): XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, **kwargs):a Can we eliminate the call signature? I think this is only necessary for extension code, the call signature will already be displayed by sphinx and by pythons interactive help. Regarding the crazy pyplot error, I'm doing it the slow, painful way, including a few members at a time in the members list and fixing the errors that arise. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Friday 23 May 2008 6:06:30 pm Eric Firing wrote: xcorr(*args, **kwargs) XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, **kwargs): Sorry I'm not helping yet, but while you are in the middle of all this, please ditch the ugly and misleading Matlab-style capitalization of the function names. Thanks for all the work and amazing progress. Some of these docstrings are *really* hard to trace. Where does pyplot.arrow get its docstring? It looks like it comes from axes.arrow, which gets a bit from patches.FancyArrow, which gets a bit from patches.Patch, which gets a bit from artist.kwdocd['Patch'] at the top of patches.py. However, I have completely rewritten artist.kwdocd['Patch']: artist.kwdocd['Patch'] = = == PropertyDescription = == alpha float animated[True | False] antialiased or aa [True | False] clip_boxa matplotlib.transform.Bbox instance clip_on [True | False] edgecolor or ec any matplotlib color facecolor or fc any matplotlib color figure a matplotlib.figure.Figure instance fill[True | False] hatch unknown label any string linewidth or lw float lod [True | False] transform a matplotlib.transform transformation instance visible [True | False] zorder any number = == but the change has not propagated up to pyplot.arrow. I have to break here for the weekend, I'll be back monday afternoon. Leave some for me! (although I'll owe doughnut to whoever can fix the arrow docstring). Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Fri, May 23, 2008 at 6:14 PM, Darren Dale [EMAIL PROTECTED] wrote
I have to break here for the weekend, I'll be back monday afternoon. Leave
some for me! (although I'll owe doughnut to whoever can fix the arrow
docstring).
I'll claim that doughnut.
This is a bit complicated. The problem is that we have to do the
interpolation into the patch doc strings at class definition time (eg
for Patch and Rectangle), but we can't use the object inspector and
doc string generator artist.kwdoc to automatically generate them until
*after* they are defined. So we have a bit of a race condition. The
solution, which is not terribly elegant, is to define the string for
the *classes* manually with the setting at the top of
matplotlib.patches:
artist.kwdocd['Patch'] = \
alpha: float
animated: [True | False]
antiali
We interpolate this into the class docstrings. Once the classes are
defined, we can introspect the class and auto generate the strings for
use in *methods* that operate on class instances. At the bottom of
patches:
artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon',
'Wedge', 'Arrow',
'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse'):
artist.kwdocd[k] = patchdoc
so the changes you make in the kwdocd dict will affect the classes in
matplotlib.patches, bu will not affect the docstrings in the plotting
functions, eg matplotlib.axes.Axes.arrow, which will use the
auto-generated version from artist.kwdoc. So you need to make your
changes in two places: in the kwdocd dict at the top of patches, as
you did before, *and* in the artist.kwdoc function which
auto-generates the property tables. If this function returns rest
tables, you will be in good shape. It is not good design to have to
make the changes in two places, but when we implemented this we could
not find a way to do the class doc string interpolation after the
class was defined, but we still wanted to use the autogenerated docs
where possible (eg in methods that handle artists like the plotting
methods) since the auto-generated stuff is more likely to remain
current.
Maybe an entry in the developer's guide is warranted
Enjoy your vacation.
JDH
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
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/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Thursday 22 May 2008 09:56:04 am John Hunter wrote: On Thu, May 22, 2008 at 8:15 AM, Darren Dale [EMAIL PROTECTED] 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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Thursday 22 May 2008 02:05:14 pm John Hunter wrote:
On Thu, May 22, 2008 at 12:48 PM, Darren Dale [EMAIL PROTECTED]
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
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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
-
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Darren Dale Sent: Thursday, May 22, 2008 6:15 AM To: matplotlib-devel@lists.sourceforge.net 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/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net 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 - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Thu, May 22, 2008 at 9:21 PM, Robert Kern [EMAIL PROTECTED] wrote: jsMath! http://www.math.union.edu/~dpvc/jsmath/ It's unfortunate that whenever LaTeX math on the web gets brought up, MathML is what everyone thinks of. I guess someone has to write the docutils code for it, though. this has *your* name written all over it JDH - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
For those of you wondering what is sphinx? this will save you a few seconds of searching: http://sphinx.pocoo.org/ The output looks really nice. Darren Dale wrote: There was some discussion a while back concerning upcoming changes to the mpl documentation: moving the docs into the trunk and updating the website. I can't find the thread now, could anyone summarize the current thinking? Ondrej Certik recently implemented a sphinx-based documentation for ipython1 (see http://ipython.scipy.org/doc/ipython1/html/ and http://ipython.scipy.org/doc/ipython1/ipython1.pdf), I wonder if we should consider doing the same for matplotlib. I haven't had nearly as much time to contribute to matplotlib as I did when I was still in grad school, but I think I will have some free time starting in May and would like to contribute some more over the summer. Now is probably a good time to start considering summer projects. Darren - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
On Tue, Mar 25, 2008 at 7:38 AM, Darren Dale [EMAIL PROTECTED] wrote: There was some discussion a while back concerning upcoming changes to the mpl documentation: moving the docs into the trunk and updating the website. I can't find the thread now, could anyone summarize the current thinking? Ondrej Certik recently implemented a sphinx-based documentation for ipython1 (see http://ipython.scipy.org/doc/ipython1/html/ and http://ipython.scipy.org/doc/ipython1/ipython1.pdf), I wonder if we should consider doing the same for matplotlib. I'm definitely up for this or something close to it. We definitely want rest based docs which live in svn alongside the src distribution. If something like sphinx on top of it makes for better documents, I'm all for it. You may have seen that over the weekend I added a couple of API rst documents to the doc subdir, with some basic make.py support for building them into PDFs. If you or anyone would like to take a stab at getting a sphinx implementation going, have at it. JDH - This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse012070mrt/direct/01/ ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Hey guys, sorry for the silence, mostly on travel. I just wanted to mention that the sphinx machinery seems quite nice, in particular it produces both high-quality pdf and client-side searchable html. This is great, because it measn that the entire doc set is automatically searchable for the users in a convenient manner, even when running offline and without the need for any special server config (and in a more civilized fashion than brute-forcing grep searches). Also, Sympy (led by Ondrej), ipython, mayavi2 and at least neuroimaging.scipy.org have all committed to using this system, and we hope in the future numpy and scipy will follow suit (at least Jarrod Millman and Stefan van der Walt, who are doing lots of work on those, are fully on board with the idea). It would be really nice if all these projects could offer unified, consistent docs to their users, and having MPL jump along would be great. Cheers, f - Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
Fernando Perez wrote: Hey guys, sorry for the silence, mostly on travel. I just wanted to mention that the sphinx machinery seems quite nice, in particular it produces both high-quality pdf and client-side searchable html. This is great, because it measn that the entire doc set is automatically searchable for the users in a convenient manner, even when running offline and without the need for any special server config (and in a more civilized fashion than brute-forcing grep searches). Also, Sympy (led by Ondrej), ipython, mayavi2 and at least neuroimaging.scipy.org have all committed to using this system, and we hope in the future numpy and scipy will follow suit (at least Jarrod Millman and Stefan van der Walt, who are doing lots of work on those, are fully on board with the idea). It would be really nice if all these projects could offer unified, consistent docs to their users, and having MPL jump along would be great. 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. Thanks, Bryce - Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] future of mpl documentation
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. Gaël - Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
