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

[Peter Cock]

A question to you all: Do any of you actually use the Biopython
Tutorial & Cookbook "offline"? i.e. The Tutorial.html or Tutorial.pdf which
we've been including in the source code releases.

Is it worth our while spending time creating a single file HTML or PDF
as part of the release process, or is the online HTML enough?

If so, that's now largely automated which would make the release
process much simpler. Historically making those files has been a major
part of the human effort in our release process (including getting the
relevant tools installed). We can in principle do the same via Sphinx,
but it is worthwhile?

Peter

On Thu, Jan 4, 2024 at 10:07 AM Peter Cock <p.j.a.cock at googlemail.com> wrote:
>
> 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