[Biopython-dev] Tutorial & Cookbook

[Peter]

Brad wrote:
>Michiel wrote:
>> A cookbook on the Wiki could be helpful though, and since the Wiki
>> pages can be fixed easily we won't have to worry so much about
>> inconsistencies with the official documentation.
>> [...]
>> +1 for the wiki, -1 for another HTML/PDF document.
>
> Same vote for me. I am responsible for the LaTeX file, but if I were
> starting it today would do things entirely on the web. The barrier
> to contributing is much lower.

One of the nice things about the current PDF (and HTML) file is we can
ship it with each release, meaning it can be used while offline.  Also
it means we don't have to worry too much about having our online
documentation deal with older versions of Biopython.

But you are right that LaTeX is a slight barrier to contributing -
although it wasn't an issue for me personally as I learnt LaTeX during
my Maths/Physics undergraduate degree.  In anycase, I've previously
said that if people have additions for the tutorial, I'll take plain
text and do the mark up for them.

>> > On the other hand, it would be very good if all our cookbook use cases
>> > could be rolled into the unit test framework - which wouldn't be so
>> > easy if they live on the wiki.  Something based on doctests might work...
>
> This is a good idea; broken examples in documentation are definitely
> annoying. If we enforce a common format for cookbook items, then we
> could scrape the wiki pages, extract the python code and run it as
> part of the tests.

That sounds possible - we might be able to scrape the wiki page,
reformat it and feed it into doctests... although testing graphical
output will still be a problem.

Speaking of doctests, we should do more of those in our docstrings.
For our online API documentation at
http://biopython.org/DIST/docs/api/ it would be nice to have the
python examples within the docstrings (including the doctests) shown
with syntax colouring.  See
http://epydoc.sourceforge.net/manual-epytext.html#doctest-blocks for
an example, and compare this to
http://biopython.org/DIST/docs/api/Bio.Seq-module.html - maybe we need
to adjust our indentation?

Peter