[Biopython-announce] Biopython Tutorial no longer written in LaTeX, but RST

[Peter Cock]

As an example, consider this page:

https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html

The "Edit on GitHub" link takes you to the source page is here:

https://github.com/biopython/biopython/blob/master/Doc/Tutorial/chapter_seq_objects.rst

Note the section links (HTML anchor names) are more friendly now, consider:

http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html#sec24

vs:

https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html#transcription

This is an example which still needs tweaking following the conversion.
The original approach of using a LaTeX table with vertical arrows and
centered alignment is probably not going to work as nicely in RST.
Perhaps a figure is better here instead?

Peter

On Thu, Jan 4, 2024 at 10:04 AM Peter Cock <p.j.a.cock at googlemail.com> wrote:
>
> Hello all,
>
> It has taken years, and efforts at several of the BOSC CoFest meetings,
> but finally the changes to convert the Biopython Tutorial and Cookbook
> from LaTeX into reStructuredText (RST) are live:
>
> https://biopython.org/docs/dev/
>
> We had previously standardized all the in-code documentation using
> Python's docstring system into RST and switched from the obsolete
> epydoc tool to using Sphinx for for the API documentation:
>
> https://biopython.org/docs/dev/api/
>
> This change means Sphinx is now also used to build the Tutorial and
> Cookbook at the same time, giving consistent HTML output. We can
> in theory also output this in PDF or eBook formats (not done yet).
>
> The RST markup language is similar to Markdown, but slightly more
> powerful for larger documents, and was developed within the Python
> ecosystem. This change means new contributors won't need to learn
> LaTeX, but also we don't need the LaTeX tools installed to build the
> documentation - something which was a barrier to doing this as part
> of the continuous integration testing.
>
> At the time of writing the old URLs do not yet redirect:
>
> http://biopython.org/DIST/docs/tutorial/Tutorial.html
> http://biopython.org/DIST/docs/tutorial/Tutorial.pdf
>
> We will keep the historic versions as there are, e.g.
>
> http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html
> http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.pdf
>
> I would encourage all of you to proof read your favorite sections
> on the new Sphinx output, and if you spot a typo there is an
> "Edit on GitHub" link top right of each page... many eyes make
> light work?
>
> Thanks all,
>
> Peter