[Biopython-dev] Documentation

[Peter]

On Wed, Jul 14, 2010 at 12:42 AM, Eric Talevich <eric.talevich at gmail.com> wrote:
> 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.

You'll be fine then - once epydoc is installed (easy on Linux as it should
be in your distribution's packages) its just one line to execute - see also:
http://biopython.org/wiki/Building_a_release

>> 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.

As Eric says, we would suggest starting with docstrings.

> 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

Note that with epydoc you can have different python files using different
mark up (this is the __docformat__ thing Eric mentioned). Most of ours are
plain text, some use epytext, soon some will use reStructuredText. The
advantage of this is we can translate things gradually (file by file).

Anything already using epytext should be quite clear and easy to convert
to reStructuredText. Anything using plain text may need a little more work.
Personally I'd suggest you pick modules you are familiar with to update
first.

Peter