[Biopython-dev] documentation for modules: happydoc/epydoc ?

[Brad Chapman]

Hi Harry;

> I'm trying to put some code in shape for submission to BioPython.  It's
> for handling data from Affymetrix GeneChips.  It's efficiently handles
> both the DAT image files and the probe cell data including the probe
> sequences.  

Great! We could definitely use something like this. Thanks for
writing it and thinking of submitting it.

> The first thing that I want to do is take care of
> documentation.
> I'm not sure if I should be using happydoc or epydoc.  

Well, you don't really need to use either. These are just
automated ways to extract documentation from the source code
(module, class and function documentation) so that they are readable
on the web. The important thing is to have good documentation of
your code and then it will extract it.

At the bottom of our guide for contributing:

http://www.biopython.org/docs/developer/contrib.html

there are some hints about writing documentation strings so that
epydoc (which is what we are using now) can deal with them best.

> I'm also not
> sure how to get both html and pdf documentation from the same source.

This is a bit of a different question. If you'd like to write
separate cookbook-style documents for how to use your code (which is
definitely encouraged) you can write them in any format you like
which is displayable on the web. Plain text or HTML (preferrably
simple, hand-edtiable HTML -- not MS Word generated type) is fine.
The PDF/HTML documentation is generated using LaTeX along with HeVeA
to make the HTML. But if you don't know LaTeX -- any way to write it
that you like is great.

> Is the code in C and C++ modules documented in a separate way?

I'd just encourage good C commenting here. Not knowing how your
modules work, I'd assume you have some Python code wrappers around
the C code so that people don't access the C-written code directly.
In that case, it's most important that the code itself is documented
so that others can understand what you wrote and how to find or fix
bugs, if any come up.

Thanks again and be sure to write if you have other questions!
Brad