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

[Peter Cock]

Likewise.

I haven't given up on getting a nice PDF yet (it can be made
to work but there are rather more warning messages than I'd like).

The Sphinx single-file HTML output is OK, but lacks the nice
table of contents and search.

Rather we might just include the many-file HTML in the
source code zip/tar-ball?

Peter

On Thu, Jan 4, 2024 at 7:37 PM Sean Brimer <skbrimer at gmail.com> wrote:
>
> Hi Peter,
>
> I only use the online version so I do not think the extra work is needed, however I do live in an area that has very reliable internet so there is that.
>
> Sean
>
>
> On Thu, Jan 4, 2024 at 10:43 AM Peter Cock <p.j.a.cock at googlemail.com> wrote:
>>
>> 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
>> _______________________________________________
>> Biopython mailing list  -  Biopython at biopython.org
>> https://mailman.open-bio.org/mailman/listinfo/biopython