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 <[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.
>>>
>>>
>> 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
>> Matplotlib-devel@lists.sourceforge.net
>> 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
-------------------------------------------------------------------------
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
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
