[Biopython-dev] Documentation

[Peter]

On Thu, Jul 15, 2010 at 5:00 AM, Vince S. Buffalo <vsbuffalo at gmail.com> wrote:
> 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.

I think the docstrings should be the primmary API documentation,
and the Tutorial the primary introductory text.

We currently have three forms,
* Biopython Tutorial (PDF & HTML, written in LateX) which is the main
documentation and should be introductory.
* Module docstrings for the API, more technical (shown online with epydoc
which is functional but ugly, later this will use SPhinx)
* Some wiki pages, more for recent things still in flux, and some user
contributed "Cookbook" entries. The wiki is nice to edit for user contributions,
but not under source code control.

>
> Also, has a branch been created on github?
>

No - I was suggesting you make a fork and your own branch, and we will
periodically review your changes and apply them to the trunk. Is that OK?

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

If in doubt, its better to ask first - so not a problem at all.

> 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

The epydoc version is here (deep linking to avoid the frames):
http://biopython.org/DIST/docs/api/Bio.SeqIO-module.html
The core text isn't so different, I'm more excited about the section
names and navigation side of things with SPhinx.

Peter