[Biopython-dev] Documentation

[Vince S. Buffalo]

>
>  I think the docstrings should be the primmary API documentation,

and the Tutorial the primary introductory text.


I like the idea of code and documentation living together, but one thing
that concerns me is that as the documentation grows larger and filled with
more examples, it may begin to clutter the code quite a bit. Separate
documentation and code allow greedy search and replace in documentation with
the guarantee it won't damage code. And in Emacs (and other editors I
presume) there are ReST editing modes that highlight syntax that do not work
in docstrings.

The benefits of documentation and code living together are that developers
can more easily find and update documentation on their functions, which is
not to be underestimated. It is interesting that numpy seems entirely
documented in docstrings, but django and other projects less so.


> (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?
>

Ah, in looking at numpy's ReST source (i.e.
http://docs.scipy.org/numpy/source/numpy/dist/lib64/python2.4/site-packages/numpy/lib/function_base.py#347)
it is much more terse. I can switch to this approach and skim their their
source to find their preprocessor.


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


I was getting this same feeling as I was working. It might not be a bad idea
to create a stub-type docstring for every non-internal function so at the
very least something ends up on the documentation. This would also provide a
template for standardizing parameters (e.g. indicating return value types,
etc). This would likely increase the length of all code files quite a bit
through, but the documentation coverage would be higher.

-- 
Vince Buffalo
Programmer
Bioinformatics Core
UC Davis Genome Center
University of California, Davis

"There's real poetry in the real world. Science is the poetry of reality."
-Richard Dawkins