[Biopython-dev] Documentation

[Eric Talevich]

2010/7/13 Peter <biopython at maubp.freeserve.co.uk>

> 2010/7/12 Eric Talevich <eric.talevich at gmail.com>:
> > Peter wrote:
> >> 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,
> > ...
>
> So in order to move the API docs to Sphinx, they have to be formatted
> as reStructuredText (rather than plain text or epytext as we use now)?
> The good news is epydoc can also support reStructuredText (important
> during transition). That will be a big bit of work, but can be done on a
> module by module basis.
>
> See:
> http://epydoc.sourceforge.net/othermarkup.html#restructuredtext
>

Yeah, I think that's the best way to go. I once considered using
reStructuredText for Bio.Phylo instead of epytext, but was deterred by the
extra dependency. So, my branch for this (not on github yet) will first just
convert all the docstrings to at least work with reStructuredText, and
hopefully the plain-text docstrings will generally Just Work.

Once that's done, and Epydoc will handle all the docstrings as
reStructuredText without any problems, I think it would be a good time to
merge that work into the trunk so we can all start/continue writing
rst-compatible docstrings.


> > ...
> > then start a reference manual under Doc/reference/ after that.
>
> Can you clarify what you idea is here? Split the current Tutorial.tex
> LaTeX file into a more introductory walk through, and a more technical
> reference manual? I'd rather more technical material into the API
> docs (i,e. the docstrings) and keep Tutorial.tex more introductory.
>
>
As I understand it, using Sphinx for API docs requires creating a .rst
document for each sub-package. The document can be a stub, containing just a
command to pull in the module docstrings:
http://sphinx.pocoo.org/ext/autosummary.html

Incidentally, we could set it up to run doctest from here, too:
http://sphinx.pocoo.org/ext/doctest.html

In any case, I won't touch Tutorial.tex at first. I'll just set up the stubs
for pulling in docstrings, and call that a minimal Sphinx reference manual,
separate from the Tutorial. Then we should figure out how to make the
reference manual easy to view (at least for anyone with a Git branch), and
at least think about how it should be published on biopython.org -- I think
it's just static .html files, so this shouldn't be too hard.

Once we're happy with Sphinx as a replacement for Epydoc, and are able to
make the reference manual available through the same sources as the
Tutorial, then we'd be free to move pieces of the Tutorial to the reference
manual, as appropriate -- adding longer descriptions and examples to the
.rst documents that were previously just stubs.

For example, my Bio.Phylo chapter in the Tutorial has detailed API
descriptions that should be moved to the reference. The BLAST chapter has a
complete class diagram which also seems like reference material to me.
There's also some BioSQL material scattered around the internet that would
be more helpful if aggregated into a complete, up-to-date reference.

Sound like a plan?

-Eric