[Biopython-dev] Documentation

[Eric Talevich]

On Fri, Jul 9, 2010 at 4:15 AM, Peter <biopython at maubp.freeserve.co.uk>wrote:

> On Thu, Jul 8, 2010 at 11:19 PM, Eric Talevich <eric.talevich at gmail.com>
> wrote:
> > So, if we were to go that route, the upgrade path would look like:
> >
> > 1. Add docutils as a dependency for building the API docs, in addition to
> > epydoc.
> > 2. Convert the docstrings that use epytext to use ReStructuredText
> instead.
> > (grep will help, and the changes are pretty robotic.)
> > 3. When all docstrings are rst-compatible (plain text is OK), try running
> > Sphinx with a stub page that just pulls in all the docstrings under Bio.
> (Or
> > something like that.) Does it work?
> > 4. If it works, figure out how to put the Sphinx-generated docs on
> > biopython.org so people can use them.
> > 5. Now that we have a bunch of stub pages that pull in each module's
> > docstrings, start adding value to those stubs by moving
> API-reference-style
> > parts of the wiki and Tutorial into the sphinx stubs.
>
> i.e. Move from epydoc to sphinx? That would probably make things much
> prettier - and could make the docstrings more accessible. We could even
> move the main tutorial from LaTeX to sphinx as well - it can make nice
> HTML and PDF files.
>

OK, I'll start a branch for this on GitHub. Do you have a preference for how
I handle the new docutils dependency? I thought I'd just document it
somewhere, similar to how the Tutorial's current hevea dependency is
mentioned.

I'll work on getting epydoc to work with docutils/ReStructuredText first,
then start a reference manual under Doc/reference/ after that.


> > 6. Semi-independently of this, try trimming the Tutorial a bit to make
> some
> > nice wiki pages.
>
> Wiki pages have some major drawbacks for primary documentation - they
> are not in git for a start which means version tracking is separate from
> the
> code version tracking. They also would be hard to bundle into the offline
> documentation. I'm not keen on this, beyond moving some "cookbook"
> examples to the wiki.
>
>
OK. I'll leave this part for the end, then, and just make note of which
parts of the Tutorial seem tangential enough to be moved to cookbook pages
on the wiki. I expect a bigger portion of the Tutorial could be moved to the
new reference manual instead -- for example, most of the API explanations in
the Phylo chapter.

I like the way simuPOP separates the user guide and reference, although the
Table of Contents pages are a little unwieldy...

Best,
Eric