[Biopython-dev] Documentation

Peter biopython at maubp.freeserve.co.uk
Thu Jul 15 10:23:30 UTC 2010


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



More information about the Biopython-dev mailing list