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

👍

Peter Cock reacted via Gmail
<https://www.google.com/gmail/about/?utm_source=gmail-in-product&utm_medium=et&utm_campaign=emojireactionemail#app>

On Thu, Jan 4, 2024 at 7:37 PM Sean Brimer <[email protected]> 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 <[email protected]>
> 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 <[email protected]>
>> 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 <[email protected]>
>> 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  -  [email protected]
>> https://mailman.open-bio.org/mailman/listinfo/biopython
>>
>

_______________________________________________
Biopython mailing list  -  [email protected]
https://mailman.open-bio.org/mailman/listinfo/biopython