[Biopython-dev] Documentation

[Eric Talevich]

Hello everyone,

I recently read this interesting article by one of the Django developers:
http://jacobian.org/writing/great-documentation/what-to-write/

The post describes three kinds of documentation a software project should
have:

1. A tutorial giving an overview of the project's major areas -- not
covering every feature, but giving the user a good enough understanding of
the whole project.

The Biopython Tutorial and Cookbook already covers this very well. If
anything, we may have put more detailed information than necessary into the
Tutorial. The length may also be a bit overwhelming for newcomers.

2. Topic guides for each of the project's components.

As I understand it, the wiki should fill this role. We could manage this
(and #1, simultaneously) by converting some less-essential portions of the
Tutorial to wiki pages.

3. A detailed reference for the complete API.

The article specifically states that docstring converters like epydoc are
insufficient, and may give developers a false sense of having taken care of
this part of the documentation.

The Python project uses Sphinx now, as do quite a few other projects. It
uses ReStructuredText as the markup syntax, and can (1) pull in docstrings
automatically, and (2) run doctest on code samples. I think this would work
nicely for Biopython.

http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

This would add a developer dependency on Docutils, a very healthy project,
and of course Sphinx. Epydoc can also accept ReStructuredText as the markup
syntax in docstrings, in place of epytext, if docutils is available.

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.
6. Semi-independently of this, try trimming the Tutorial a bit to make some
nice wiki pages.

Does this sound worthwhile?

All the best,
Eric