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

[Peter]

> 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.

I've done Bio/SeqIO/QualityIO.py as well which proved harder due
to lots of example FASTQ records embedded in the text.

I've also worked out how to set the epydoc markup format on a per
file basis with the __docformat__ setting (see also PEP 258).  This
means we can gradually convert existing docstrings on a file by file
basis - I'd suggest we focus on those with docstrings first, as they
will benefit most from this.

The only downside thus far is that the epytext mark up seems rather
fragile, and it is easy to "break" a docstring such that epydoc fails to
render nicely.  At least epydoc falls back on plain text in this situation,
so the text is still human readable.

Tip: You need an EMPTY line before and after each doctest in order
for it to work with epydoc as epytext markup.  This is annoying as
the doctest framework can cope with a line with spaces in it.

Peter