[Biopython-dev] Documentation

[Peter]

On Tue, Jul 13, 2010 at 4:17 PM, Eric Talevich <eric.talevich at gmail.com> wrote:
>Peter wrote:
>> 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.

Sounds good. I would like to keep the reStructuredText as simple
as possible for human readers (i.e. when looking at the doctext
within Python). I think the NumPy project had similar aims, and
have documented this - e.g. here:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines

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

That fits with my impression from chatting to NumPy folk at
EuroSciPy 2010. Loads of stub RST files sounds like a bit of
a pain, but I can live with it.

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

Sounds OK...

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

Or move them into the module docstrings instead?

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

Regarding BioSQL, what online bits are you referring to beyond this:
http://www.biopython.org/wiki/BioSQL (and the LaTeX file referenced)?

Peter