[Biopython-dev] Documentation

[Peter]

On Thu, Jul 8, 2010 at 11:19 PM, Eric Talevich <eric.talevich at gmail.com> wrote:
> Hello everyone,
>
> I recently read this interesting article by one of the Django developers:
> http://jacobian.org/writing/great-documentation/what-to-write/

I don't agree with everything he said, but interesting.

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

His idea of an introductory tutorial is more a walk though example.

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

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.

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

Peter