[Biopython-dev] Documentation

[Peter]

On Thu, Jul 15, 2010 at 10:18 AM, Peter <biopython at maubp.freeserve.co.uk> wrote:
>>
>> Also, has a branch been created on github?
>>
>
> No - I was suggesting you make a fork and your own branch, and we will
> periodically review your changes and apply them to the trunk. Is that OK?

It looks like you are already doing that - great. A few things from looking over
your first two commits, for SeqIO and AlignIO,

http://github.com/vsbuffalo/biopython/commit/a77d168cdf3f4a2c36708b5553531eef216f8aec
http://github.com/vsbuffalo/biopython/commit/76ba2d5e9c5d915230bbdee73fa3a3a962f814df

(1) Until most of the docstrings are using reStructuredText, we need to keep
using epydoc (before switching to SPhinx). During this transition we will
have a mix of mark up in different modules. The __docformat__ setting
is important to tell epydoc this. So rather than deleting any existing value
like:

__docformat__ = "epytext en"

it should probably be replaced with:

__docformat__ = "reStructuredText en"

See http://epydoc.sourceforge.net/othermarkup.html

(2) I'm not keen on things like :mod:`Bio.AlignIO` or :func:`write` in the
markup. They look ugly and confusing to me (for looking at the raw text
at the Python terminal). Have you looked at NumPy's guidelines
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
and whatever pre-processors they use to assist Sphinx?

(3) Do you think we should we also be standardising how we describe
parameters in docstrings? e.g. Follow what NumPy is doing?

Peter