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
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/vse0120000070mrt/direct/01/ > _______________________________________________ > Matplotlib-devel mailing list > Mat...@li... > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
On Tue, Mar 25, 2008 at 7:38 AM, Darren Dale <dar...@co...> 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
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
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
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
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
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
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
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.
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 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
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
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 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 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 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
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 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
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 6:34 PM, Ted Drain <ted...@jp...> wrote: > 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. That would be great. > 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... This should be really easy. The top level doc, index.txt will just be a bunch of include files. It would be no problem to write your own top level include document, which mixes our sections and chapters with your own as you see fit. Feel free to use the svn doc tree -- eg you can add a html_pdf or pdf_jpl build command to the make.py file that builds your own docs which include our stuff plus your own custom stuff. Or if you want to set up a framework outside of our tree that supports hooks, give it a whirl and let us know what we can do on our end to help. As far as contributions, a units chapter would be most welcome, as would anything else you can contribute. I'd like to have a UI chapter which would include a section for each backend UI, so you might want to consider a "Using matplotlib with qt" section since you are co-authors of the qt backend. BTW, I understand that you guys (and mpl by extension) have a big day coming up Sunday with the Phoenix landing. Good luck! Thanks
On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pki...@ni...> 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. JDH
On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote: > On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pki...@ni...> 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
On Friday 23 May 2008 7:08:09 am Paul Kienzle wrote: > On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote: > > On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pki...@ni...> 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. I moved them when I updated mpl to split the API reference from the Users Guide: http://dale.chess.cornell.edu/~darren/temp/matplotlib/ I just heard from Jens again, he has another extension that uses png's rather than mathml. I'll try it when I get to work this morning, it should work in all browsers and we can use regular html files. Darren
These examples look great, Darren. One small detail: The cover page of the PDFs list John and Darren as authors. I think the docs (particularly the docstrings) have probably been written by a much larger community. If it's not practical to list all contributors (probably so given all of the hands that have worked on this over the years), maybe John and Darren could be credited as editors. Cheers, Mike Darren Dale wrote: > On Friday 23 May 2008 7:08:09 am Paul Kienzle wrote: > >> On Thu, May 22, 2008 at 08:45:02PM -0500, John Hunter wrote: >> >>> On Thu, May 22, 2008 at 6:08 PM, Paul Kienzle <pki...@ni...> 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. >> > > I moved them when I updated mpl to split the API reference from the Users > Guide: http://dale.chess.cornell.edu/~darren/temp/matplotlib/ > > I just heard from Jens again, he has another extension that uses png's rather > than mathml. I'll try it when I get to work this morning, it should work in > all browsers and we can use regular html files. > > 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 > -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA