[Biopython-dev] Documentation

[Vince S. Buffalo]

Hi all,

I've started the conversion process with the file Bio/SeqIO/__init__.py. A
few questions came up.

First, are docstrings (with the autodoc extension) going to be the primary
form of documentation, or are we going to copy/paste them into a separate
documentation tree? I believe the latter is what Python and Django do, and
may give us freedom to target different audiences with docstrings and the
separate documentation. Also, after some Googling about autodoc, it seems
complex.

Also, has a branch been created on github?

At this point, I'll continuing going through the "robotic" steps of
converting epydoc formatting to ReST. Given my youthfulness working on this
project, I'll try to keep you guys well updated. Preemptive apologies for
future questions :-)

Also, to test ReST + Sphinx on one section, I ran Sphinx on a copy/pasted
docstring. I have to say, Sphinx is beautiful: http://imgur.com/4gNok

best,
Vince

On Wed, Jul 14, 2010 at 11:24 AM, Vince S. Buffalo <vsbuffalo at gmail.com>wrote:

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


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