[Biopython-dev] Epydoc markup

[Brad Chapman]

Hi Thomas;

> First of all - thanks for shipping 1.30! Nice job!

Thanks to you as well -- there has been lots of nice work with the
PDB and structure molecules in well. There is some really impressive
stuff in there.

> Small remark: I noticed that the Epydoc markup language
> in the doc strings of the Bio.PDB module is not translated into
> HTML in the documentation on the website. If I run Epydoc locally
> everything looks fine, though. Any idea what could be wrong? 

Well, I've been using '--docformat plaintext' when running epydoc. I
do like the epydoc markup, but it seems like if something isn't
marked up then it can come out looking pretty unreadable.

A good example is the Fasta package, in which it munges together all
of the information in the header:

Classes: Record Holds FASTA sequence data. Iterator Iterates over
sequence data in a FASTA file. Dictionary Accesses a FASTA file
using a dictionary interface. RecordParser Parses FASTA sequence
data into a Record object. SequenceParser Parses FASTA sequence data
into a Sequence object.

I'm not sure if there is a way to specify specific modules, like
yours, which use epydoc and get it to treat them differently. I'll
have to look at it a little more.

> BTW,
> is there a way for the Biopython developers to update the documentation
> on the website directly? Might be useful.

Hmmm I don't think you account on biopython.org right now. Would you
like me to give you one? If so, just send me a separate mail and
I'll set you up with your same account name and a temporary
password. The details of where things are on the server and how the
web pages work are at:

http://www.biopython.org/docs/developer/website_technical.html

> Epydoc is a great tool, BTW. It was a very good idea to
> introduce it, IMO.

I think so as well -- I'm glad people are into using it. The output
is much more usable and pointing people at it is a great way to get
an overview of what's in Biopython.

Brad