[Biopython-dev] Documentation

[Peter]

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

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

Regards,

Peter