[BioPython] pending developmental release

[Brad Chapman]

Jeff Chang wrote:
> Great!  We'll make it at the end of the week, then.  Friday, or
> Saturday...

That sounds super to me. I'll send you a mail when I think biopython-corba
is ready to go.

> I've started the barest outline of a tutorial in
> biopython/Doc/Tutorial.txt with some ideas of things to put in.  However,
> I'm not set on the content.  In any case, we should target it toward as
> wide an audience as possible, without having to give a CS or biology
> lesson.
>  
> Is this what you had in mind to do?

Yup, you're a mind reader :-). Seriously, the ideas in Tutorial.txt sound
good, so I think a good next step would be to flesh it out into a real
outline of sections, etc. Then we can think about how to divide the work
of writing the documentation up. If you want, I can take a stab at getting
an outline going based on what you already have, and then we can have
your ideas and mine in the first outline. Maybe some other people also
have ideas on what should be included.
 
> Also, if you have any ideas on what kind of format we should use for
> documentation (LaTeX, Word, HTML, Text, etc.), please let me know.  
> Python doesn't have the nice POD or javadoc stuff...

I would very much prefer to write in LaTeX (especially over Word, bleah).
I have had really good luck doing "technical" documentation in it using
verbatim to typeset code examples. In addition, it also produces lots of
nice formats, and I have been converting LaTeX to html regularly using
HeVeA (http://pauillac.inria.fr/~maranget/hevea/index.html) with good
luck.

> Hmmm...  Most of the code does have docstrings, so we should look 
> into the
> state of docstring programs.

AFAIK, there are three separate implementations to convert docstrings into
some readable output:

pythonddoc -> http://starship.python.net/crew/danilo/pythondoc/
crystal -> http://www.btinternet.com/~tratt/comp/python/crystal/
htmldoc -> http://www.lfw.org/python/ (at the bottom of the page)

I have tried all of these without any success, so I don't have a personal
recommendation :-< (They all seem to not work well on programs with
dependencies on modules that aren't from the core library, but we
shouldn't have these problems with biopython). However, htmldoc should be
easiest since it is only two modules and doesn't try to do anything like
format docstrings (which crystal and pythondoc do).

Brad