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

[Sean Brimer]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.open-bio.org/pipermail/biopython/attachments/20240104/a50c2c4a/attachment.htm>