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

[Peter]

On Fri, Apr 17, 2009 at 2:30 PM, Brad Chapman <chapmanb at 50mail.com> wrote:
> 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
>
> I had some time where I was obsessed with making Biopython look
> good in one of these API documentation modules (maybe HappyDoc,
> back in the day). Eventually I came to the sad conclusion that not too
> many people really seem to actually look at auto generated API docs.
> Most will fire up the code in their favorite editor if they are
> interested in the fine details.

I agree that we don't push the API docs page enough (and indeed
corresponding built in documentation).  This is a shame, as the
built in docstrings should really get more attention.  To try and raise
their profile I've added links to the relevant pages from some of the
wiki pages to try and encourage people to look at them.  There is
probably a cunning redirect link which will get the frames to work,
but I've just used deep linking on these pages for now:

http://biopython.org/wiki/Seq
http://biopython.org/wiki/SeqRecord
http://biopython.org/wiki/SeqIO
http://biopython.org/wiki/AlignIO

In fact, maybe we should simplify/remove these wiki pages and just
push the API pages and relevant cookbook wiki pages in their place?
Up until now, the wiki was nicer in that it looked better - with the
epydoc mark up that isn't the case.  The API docs should be the
definitive documentation, in that the are kept up to date with the
code, and are under version control.

> So, I like the way this looks, but my vote is it is probably not
> worth the cycles unless you are having fun with it. Also, be ready
> get mad when the preferred method of markup changes from epytext to
> structuredtext or someothertext.

I know what you mean - the novelty has worn off now, and doing
further conversions is tedious.  I like the idea of a tweak to epydoc
to do "plain text + automatic markup of doctests".  If that existed
it would be a great default option for Biopython, as all I really care
about for the markup is getting the python doctests to look good.

Peter