Hi Mike, On Friday 23 May 2008 08:34:35 am Michael Droettboom wrote: > 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. Thank you for bringing this up. I was actually thinking about this on the way to work this morning, how to give appropriate credit for everyone who has contributed to the documentation. I'll make sure this issue is addressed. Maybe when we get close to publishing these we can revisit the issue, it looks like there are several people interested in contributing, and I'm sure we all would like those efforts to receive credit. Darren
There are a couple of minor details about formatting that might be worth working out up front before too much reST conversion begins: How do we want to handle inline code names? For example, this passage from the Artist API tutorial: "The primitives represent the standard graphical objects we want to paint onto our canvas: Line2D, Rectangle, Text, AxesImage, etc, and the containers are places to put them (Axis, Axes and Figure)." 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. Personally, I prefer whatever makes the resulting documentation products the most useful, but I know there are others that make more use of the documentation in its original form. We could preprocess some of these things out, but I would only want to go down that path if it doesn't add too much complexity. 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. Cheers, Mike Michael Droettboom wrote: > 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
On Fri, May 23, 2008 at 7:34 AM, Michael Droettboom <md...@st...> wrote: > 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. I am more than happy to give credit to any and all on the author/contributer/editor list. For now, let's have anyone who had made a contribution and wants to be on the list just add your name, and when we have something sizeable, Darren can organize the list depending on how the work has been done, eg into editors, authors, contributers as appropriate. JDH
On Thu, May 22, 2008 at 4:59 PM, Darren Dale <dar...@co...> 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. 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. - 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? Great work! JDH
On Thursday 22 May 2008 10:10:13 pm John Hunter wrote: > On Thu, May 22, 2008 at 4:59 PM, Darren Dale <dar...@co...> 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
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. 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. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Thu, May 22, 2008 at 9:21 PM, Robert Kern <rob...@gm...> 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
On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> 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? JDH
John Hunter wrote: > On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> 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? > It appears to. See, for example, the :mod:`matplotlib.plab` that gets formatted in monospace in the introduction. Cheers, Mike -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA
On Friday 23 May 2008 10:54:52 am John Hunter wrote: > On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> 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.
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
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
For my fellow emacs users: If you aren't aware of it, there is a reST mode for emacs: http://docutils.sourceforge.net/tools/editors/emacs/rst.el In the course of experimenting today, I wrote a few elisp macros (attached) to aid in adding inline cross-references to the code that might be generally useful. By putting the cursor over a particular token, you can easily mark it as a class, function, method, module etc. For example, pressing "C-c c" over the word "Axes" will replace it with ":class:`Axes`". C-c c : class C-c m : method C-c f : function C-c a : attribute C-c o : module Cheers, Mike John Hunter wrote: > On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> 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? > > JDH > -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA
On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> wrote: > For my fellow emacs users: > > If you aren't aware of it, there is a reST mode for emacs: > > http://docutils.sourceforge.net/tools/editors/emacs/rst.el > > In the course of experimenting today, I wrote a few elisp macros (attached) > to aid in adding inline cross-references to the code that might be generally > useful. By putting the cursor over a particular token, you can easily mark > it as a class, function, method, module etc. For example, pressing "C-c c" > over the word "Axes" will replace it with ":class:`Axes`". Will rest recognize the module this comes from?- I've been using the full path :class:`matplotlib.lines.Line2D` and when I just want the Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't tested this yet since we don't have the api docs linked in, but this is how I've been writing...
John Hunter wrote: > On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> wrote: > >> For my fellow emacs users: >> >> If you aren't aware of it, there is a reST mode for emacs: >> >> http://docutils.sourceforge.net/tools/editors/emacs/rst.el >> >> In the course of experimenting today, I wrote a few elisp macros (attached) >> to aid in adding inline cross-references to the code that might be generally >> useful. By putting the cursor over a particular token, you can easily mark >> it as a class, function, method, module etc. For example, pressing "C-c c" >> over the word "Axes" will replace it with ":class:`Axes`". >> > > Will rest recognize the module this comes from?- I've been using the > full path :class:`matplotlib.lines.Line2D` and when I just want the > Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't > tested this yet since we don't have the api docs linked in, but this > is how I've been writing... > From the playing around I've done, it seems that, yes, you do need to fully specify if you're writing from outside of a docstring. However within docstrings, it seems you can refer to other methods in the same class or other classes in the same module by their name only. (My emacs macros are a little broken because they stop at '.'s, but hopefully I can fix that without going too crazy.) Cheers, Mike -- Michael Droettboom Science Software Branch Operations and Engineering Division Space Telescope Science Institute Operated by AURA for NASA
On Friday 23 May 2008 02:00:57 pm Michael Droettboom wrote: > John Hunter wrote: > > On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> wrote: > >> For my fellow emacs users: > >> > >> If you aren't aware of it, there is a reST mode for emacs: > >> > >> http://docutils.sourceforge.net/tools/editors/emacs/rst.el > >> > >> In the course of experimenting today, I wrote a few elisp macros > >> (attached) to aid in adding inline cross-references to the code that > >> might be generally useful. By putting the cursor over a particular > >> token, you can easily mark it as a class, function, method, module etc. > >> For example, pressing "C-c c" over the word "Axes" will replace it with > >> ":class:`Axes`". > > > > Will rest recognize the module this comes from?- I've been using the > > full path :class:`matplotlib.lines.Line2D` and when I just want the > > Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't > > tested this yet since we don't have the api docs linked in, but this > > is how I've been writing... > > From the playing around I've done, it seems that, yes, you do need to > fully specify if you're writing from outside of a docstring. However > within docstrings, it seems you can refer to other methods in the same > class or other classes in the same module by their name only. > > (My emacs macros are a little broken because they stop at '.'s, but > hopefully I can fix that without going too crazy.) I just discovered the figure directive: .. literalinclude:: figures/pyplot_simple.py .. figure:: figures/pyplot_simple.png :scale: 50 Here's a caption! Its not obvious in the html output that it is a caption, but in the latex output it uses the figure environment and so a caption yields a figure number. Is there a prefered size for the figures? The html figures are currently a little large for my taste, and the pdf figures are a little small. One last thing, I wonder if it would be worth pursuing the ability to include pdf files in the latex document. Maybe Georg would accept a patch that attempts to do the right thing if the extension is missing? Darren
On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> 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. But I am having trouble in that my class links are not recognized, even though I've added the relevant module to the api_artists.txt file which is included by api.txt which is included by indext.txt which builds everything. Any ideas? JDH
On Friday 23 May 2008 03:02:55 pm John Hunter wrote: > On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> 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. But I am > having trouble in that my class links are not recognized, even though > I've added the relevant module to the api_artists.txt file which is > included by api.txt which is included by indext.txt which builds > everything. Any ideas? If a member doesnt contain a docstring, it wont be included by autodoc, at least by default. You can change this by adding the undoc-members flag: :mod:`matplotlib.lines` ============================= .. automodule:: matplotlib.lines :members: :undoc-members: So Line2D was not showing up in the api chapter. I added that line in the trunk, deleted my build directory, and I can see the link now. Darren -- Darren S. Dale, Ph.D. Staff Scientist Cornell High Energy Synchrotron Source Cornell University 275 Wilson Lab Rt. 366 & Pine Tree Road Ithaca, NY 14853 dar...@co... office: (607) 255-3819 fax: (607) 255-9001 http://www.chess.cornell.edu
On Friday 23 May 2008 03:02:55 pm John Hunter wrote: > On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> 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
On Fri, May 23, 2008 at 3:00 PM, Darren Dale <dar...@co...> wrote: > On Friday 23 May 2008 03:02:55 pm John Hunter wrote: >> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> 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. OK, sounds good. I tried including the pyplot reference docs but it is croaking on the docstrings there. I suppose some of them have some invalid rest. Unfortunately the line numbers don't make a lot of sense updating environment: 17 added, 0 changed, 0 removed reading... add_new_projection api api_artists api_introduction api_pyplot reST markup error: /home/titan/johnh/python/svn/matplotlib.trunk/matplotlib/doc/users_guide/api_pyplot.txt:1127: (SEVERE/4) Unexpected section title or transition. **************** since api_pyplt.txt is just a small file which does: ***************** matplotlib.pyplot ***************** :mod:`matplotlib.pyplot` ============================= .. automodule:: matplotlib.pyplot :members: :undoc-members: Have you had any success in figuring out how to know what is causing these kinds of errors, ie where to go in the module docs to fix them? JDH
On Friday 23 May 2008 04:12:51 pm John Hunter wrote: > On Fri, May 23, 2008 at 3:00 PM, Darren Dale <dar...@co...> wrote: > > On Friday 23 May 2008 03:02:55 pm John Hunter wrote: > >> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> 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. > > OK, sounds good. > > I tried including the pyplot reference docs but it is croaking on the > docstrings there. I suppose some of them have some invalid rest. > Unfortunately the line numbers don't make a lot of sense > > updating environment: 17 added, 0 changed, 0 removed > reading... add_new_projection api api_artists api_introduction > api_pyplot reST markup error: > > /home/titan/johnh/python/svn/matplotlib.trunk/matplotlib/doc/users_guide/ap >i_pyplot.txt:1127: (SEVERE/4) Unexpected section title or transition. > > **************** > > > since api_pyplt.txt is just a small file which does: > > ***************** > matplotlib.pyplot > ***************** > > :mod:`matplotlib.pyplot` > > ============================= > > .. automodule:: matplotlib.pyplot > > :members: > :undoc-members: > > Have you had any success in figuring out how to know what is causing > these kinds of errors, ie where to go in the module docs to fix them? No, I was just having a look at that myself. Usually it gives you a little more to go on, like these which are now fixed except for the last one: WARNING: <docstring of matplotlib.artist.ArtistInspector.get_aliases>:4: (ERROR/3) Unexpected indentation. WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:17: (ERROR/3) Unexpected indentation. WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:25: (ERROR/3) Unexpected indentation. WARNING: /usr/local/src/matplotlib/matplotlib/doc/users_guide/users_guide.txt:7: (WARNING/2) toctree references unknown document u'customizing' Could you commit yout customizing.txt?
On Fri, May 23, 2008 at 3:31 PM, Darren Dale <dar...@co...> 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. JDH
On May 23, 2008, at 4:34 PM, John Hunter wrote: > On Fri, May 23, 2008 at 3:31 PM, Darren Dale > <dar...@co...> 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 don't know if you were planning to accept submissions, but here's a logo with some of my favorite plots from examples.zip:
On Sat, May 24, 2008 at 11:21 PM, Tony Yu <ts...@gm...> wrote: > I don't know if you were planning to accept submissions, but here's a logo > with some of my favorite plots from examples.zip: Submissions are extremely welcome, and I like the approach. I think you might experiment with another font for the main text, and try to incorporate some display of mathtext since this is a real selling point. We also need one version that is no wider that 200 pages for the sphinx navigation toolbar, so we will need to be judicious for that one. But the one for the web page can be much larger, and I like this as start. Is there anything we can do with the background to make it a little more interesting? A very large equation that spans most of the background but is so light in color (a gray with a low alpha) that it very faint? Also, the banner should be generated as a matplotlib figure rather than put together in inkscape or something like that. How did you make this -- if is code, please post so we can play along. If not, see if you can write the logo example by laying out the axes just so. JDH
On Sun, May 25, 2008 at 8:18 AM, John Hunter <jd...@gm...> wrote:
> Also, the banner should be generated as a matplotlib figure rather
> than put together in inkscape or something like that. How did you
> make this -- if is code, please post so we can play along. If not,
> see if you can write the logo example by laying out the axes just so.
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
JDH
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.cm as cm
import matplotlib.mlab as mlab
axalpha = 0.05
figcolor = '#FFFFCC'
dpi = 80
fig = plt.figure(figsize=(8, 2),dpi=dpi)
fig.figurePatch.set_edgecolor(figcolor)
fig.figurePatch.set_facecolor(figcolor)
# the polar bar plot
ax = fig.add_axes([0.05, 0.05, 0.2, 01], polar=True)
ax.axesPatch.set_alpha(axalpha)
N = 20
theta = np.arange(0.0, 2*np.pi, 2*np.pi/N)
radii = 10*np.random.rand(N)
width = np.pi/4*np.random.rand(N)
bars = ax.bar(theta, radii, width=width, bottom=0.0)
for r,bar in zip(radii, bars):
bar.set_facecolor( cm.jet(r/10.))
bar.set_alpha(0.5)
for label in ax.get_xticklabels() + ax.get_yticklabels():
label.set_visible(False)
# the histogram
axhist = fig.add_axes([0.275, 0.075, 0.2, 0.4])
axhist.axesPatch.set_alpha(axalpha)
mu, sigma = 100, 15
x = mu + sigma*np.random.randn(10000)
# the histogram of the data
n, bins, patches = axhist.hist(x, 50, normed=1, facecolor='green',
edgecolor='green', alpha=0.75)
y = mlab.normpdf( bins, mu, sigma)
l = axhist.plot(bins, y, 'r', lw=1)
axhist.set_title('Density of IQ',fontsize=6)
axhist.set_xlabel('IQ', fontsize=6)
axhist.set_ylabel('P(IQ)', fontsize=6)
ax.set_xlim(-2*sigma, 2*sigma)
for label in axhist.get_xticklabels() + axhist.get_yticklabels():
label.set_visible(False)
axback = fig.add_axes([0., 0., 1., 1.])
#the math background
tex = r"$W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1
\rho_1} + \frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d
\alpha^\prime_2 \left[\frac{ U^{2\beta}_{\delta_1 \rho_1} -
\alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2} }{U^{0\beta}_{\rho_1
\sigma_2}}\right]$"
axback.text(0.5, 0.5, tex,
transform=axback.transAxes, color="0.5", alpha=0.5, fontsize=40,
ha='center', va='center')
axback.set_axis_off()
# the matplotlib title
axback.text(0.3, 0.95, 'matplotlib', color='black', fontsize=75,
ha='left', va='top', alpha=1.0,
transform=axback.transAxes)
fig.savefig('logo2.png', facecolor=figcolor, edgecolor=figcolor, dpi=dpi)
plt.show()