[Biopython-dev] docstrings, doctests and epydoc API pages

[Peter]

I've changed the thread title to something a little more specific.

On Wed, Apr 15, 2009 at 1:21 PM, Peter wrote:
> We currently explicitly use plain text for epydoc, rather than the
> default epytext markup language.  If we switch to epytext (or at least
> a very simple subset of it, as some of the markup doesn't lend itself
> to friendly human readable docstrings) then we do get python syntax
> colouring on the doctests.  However, this will require some effort to
> fine tune the docstrings, and right now it makes a mess of in some
> cases.

As a test, I was able to update Bio/Seq.py to look good as epytext
(while still being equally readable as plain text for when reading the
API documentation at the python prompt with the help function). I
uploaded one new page to the website:

http://biopython.org/DIST/docs/api/Bio.Seq.Seq-class.html

The rest of the online API pages are currently still from Biopython
1.49, when epydoc parsed the docstrings as plain text.  For another
example with quite a few docstrings and doctests, look at:

http://biopython.org/DIST/docs/api/Bio.SeqRecord.SeqRecord-class.html

What do you all think?  I don't know if it will encourage more people
to look at the API pages, but I certainly like the new version where
the doctests are shown boxed with syntax colouring.

Note that this would be a lot easier to do if epydoc supported "plaintext
with doctests" as a markup type, or did this automatically when told the
markup is just "plaintext" (as I had originally hoped for).  I wonder how
easy that would be to implement... it might be less work than checking
all our API pages by hand and fixing our markup to follow epytext
standards.  See also: http://epydoc.sourceforge.net/epytext.html

Peter