[Biopython-dev] Documentation

[Vince S. Buffalo]

Thanks Eric and Peter, I'll get started on this!

best,
Vince

On Wed, Jul 14, 2010 at 3:12 AM, Peter <biopython at maubp.freeserve.co.uk>wrote:

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



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