On Dec 8, 2006, at 7:30 PM, Gary Ruben wrote:
Can you suggest something existing for the extra markup? I've never used anything fancier than plain docstrings. The other existing options seem to be (from a brief look)
reST/docutils epydoc pythondoc doxygen happydoc
Right. These all exist. They all have their issues and their benefits. I just don't see a need for yet another one. We happen to use the epydoc tool to process reST markup.
I like the idea of supporting LaTeX markup, cross references.
Alan addresses this.
I like the idea of supporting matplotlib examples (opinions?).
Supporting how? You certainly can have matplotlib code in doctest lines and you can use reST's ..image:: declaration to include output in your documentation.
I like Mark's idea of a wiki page per function/class/module if it can be done. I also don't mind William's YADMUS.
It's not that I mind his markup; it's that I don't think Python benefits from having at least a half-dozen of them. If the energy that went into developing reST, epydoc, pydoc, doxygen for Python, happydoc, and SAGE-YADMUS had gone into improving any one of them, I think the entire Python community would be better off.
The problem I see with plain doctests is that you can't easily choose to run, say, just the 3rd example out of 5 without specifying some sort of delineation between them, but this would be easy; something like: # Ex1: or Ex2 etc. between each doctest.
I'm not sure exactly what you mean by this. We have full examples of different applications of FiPy. Those are each in individual files where the entire thing is just a big docstring, including doctest lines, with a little bit of code at the end to take care of loading the doctest lines and running them. Those individual scripts can be run on their own (although simply as scripts, not as doctests). We also document the usage of individual methods with specific doctests. I can't imagine why I'd want to just run one of them.