[Biopython-dev] Documentation

[Eric Talevich]

On Tue, Jul 13, 2010 at 7:26 PM, Vince S. Buffalo <vsbuffalo at gmail.com>wrote:

> I am familiar with git, github and Sphinx, but not epydoc. Would initial
> draft version of the tutorial to Sphinx be a good first move?
>
> best,
> Vince
>
>
Hi Vince,

Converting both to Sphinx would be awesome, but if you're looking to learn
about Biopython in depth, I'd recommend starting by converting the
docstrings to reStructuredText.

In the current Biopython source tree, you can grep for "__docformat__" to
identify modules that are already using Epytext markup; those should be
converted first. See:
http://epydoc.sourceforge.net/manual-othermarkup.html

Then, you can try running Epydoc with the option to interpret all docstrings
as reStructuredText, rather than plain text. Make sure you're in a new,
empty directory outside the Biopython source tree, and use the command:

epydoc --html --verbose --docformat restructuredtext Bio BioSQL

This should identify any remaining issues, including any dependencies you're
missing.

Best,
Eric