<div><p style="font-size:50px;margin-top:0;margin-bottom:0">👍</p><p style="margin-top:10px;margin-bottom:0">Peter Cock reacted via <a href="https://www.google.com/gmail/about/?utm_source=gmail-in-product&utm_medium=et&utm_campaign=emojireactionemail#app">Gmail</a></p></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jan 4, 2024 at 7:37 PM Sean Brimer <<a href="mailto:skbrimer@gmail.com">skbrimer@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>Hi Peter,</div><div><br></div><div>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.</div><div><br></div><div>Sean <br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jan 4, 2024 at 10:43 AM Peter Cock <<a href="mailto:p.j.a.cock@googlemail.com" target="_blank">p.j.a.cock@googlemail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">A question to you all: Do any of you actually use the Biopython<br>
Tutorial & Cookbook "offline"? i.e. The Tutorial.html or Tutorial.pdf which<br>
we've been including in the source code releases.<br>
<br>
Is it worth our while spending time creating a single file HTML or PDF<br>
as part of the release process, or is the online HTML enough?<br>
<br>
If so, that's now largely automated which would make the release<br>
process much simpler. Historically making those files has been a major<br>
part of the human effort in our release process (including getting the<br>
relevant tools installed). We can in principle do the same via Sphinx,<br>
but it is worthwhile?<br>
<br>
Peter<br>
<br>
On Thu, Jan 4, 2024 at 10:07 AM Peter Cock <<a href="mailto:p.j.a.cock@googlemail.com" target="_blank">p.j.a.cock@googlemail.com</a>> wrote:<br>
><br>
> As an example, consider this page:<br>
><br>
> <a href="https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html" rel="noreferrer" target="_blank">https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html</a><br>
><br>
> The "Edit on GitHub" link takes you to the source page is here:<br>
><br>
> <a href="https://github.com/biopython/biopython/blob/master/Doc/Tutorial/chapter_seq_objects.rst" rel="noreferrer" target="_blank">https://github.com/biopython/biopython/blob/master/Doc/Tutorial/chapter_seq_objects.rst</a><br>
><br>
> Note the section links (HTML anchor names) are more friendly now, consider:<br>
><br>
> <a href="http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html#sec24" rel="noreferrer" target="_blank">http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html#sec24</a><br>
><br>
> vs:<br>
><br>
> <a href="https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html#transcription" rel="noreferrer" target="_blank">https://biopython.org/docs/dev/Tutorial/chapter_seq_objects.html#transcription</a><br>
><br>
> This is an example which still needs tweaking following the conversion.<br>
> The original approach of using a LaTeX table with vertical arrows and<br>
> centered alignment is probably not going to work as nicely in RST.<br>
> Perhaps a figure is better here instead?<br>
><br>
> Peter<br>
><br>
> On Thu, Jan 4, 2024 at 10:04 AM Peter Cock <<a href="mailto:p.j.a.cock@googlemail.com" target="_blank">p.j.a.cock@googlemail.com</a>> wrote:<br>
> ><br>
> > Hello all,<br>
> ><br>
> > It has taken years, and efforts at several of the BOSC CoFest meetings,<br>
> > but finally the changes to convert the Biopython Tutorial and Cookbook<br>
> > from LaTeX into reStructuredText (RST) are live:<br>
> ><br>
> > <a href="https://biopython.org/docs/dev/" rel="noreferrer" target="_blank">https://biopython.org/docs/dev/</a><br>
> ><br>
> > We had previously standardized all the in-code documentation using<br>
> > Python's docstring system into RST and switched from the obsolete<br>
> > epydoc tool to using Sphinx for for the API documentation:<br>
> ><br>
> > <a href="https://biopython.org/docs/dev/api/" rel="noreferrer" target="_blank">https://biopython.org/docs/dev/api/</a><br>
> ><br>
> > This change means Sphinx is now also used to build the Tutorial and<br>
> > Cookbook at the same time, giving consistent HTML output. We can<br>
> > in theory also output this in PDF or eBook formats (not done yet).<br>
> ><br>
> > The RST markup language is similar to Markdown, but slightly more<br>
> > powerful for larger documents, and was developed within the Python<br>
> > ecosystem. This change means new contributors won't need to learn<br>
> > LaTeX, but also we don't need the LaTeX tools installed to build the<br>
> > documentation - something which was a barrier to doing this as part<br>
> > of the continuous integration testing.<br>
> ><br>
> > At the time of writing the old URLs do not yet redirect:<br>
> ><br>
> > <a href="http://biopython.org/DIST/docs/tutorial/Tutorial.html" rel="noreferrer" target="_blank">http://biopython.org/DIST/docs/tutorial/Tutorial.html</a><br>
> > <a href="http://biopython.org/DIST/docs/tutorial/Tutorial.pdf" rel="noreferrer" target="_blank">http://biopython.org/DIST/docs/tutorial/Tutorial.pdf</a><br>
> ><br>
> > We will keep the historic versions as there are, e.g.<br>
> ><br>
> > <a href="http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html" rel="noreferrer" target="_blank">http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.html</a><br>
> > <a href="http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.pdf" rel="noreferrer" target="_blank">http://biopython.org/DIST/docs/tutorial/Tutorial-1.82.pdf</a><br>
> ><br>
> > I would encourage all of you to proof read your favorite sections<br>
> > on the new Sphinx output, and if you spot a typo there is an<br>
> > "Edit on GitHub" link top right of each page... many eyes make<br>
> > light work?<br>
> ><br>
> > Thanks all,<br>
> ><br>
> > Peter<br>
_______________________________________________<br>
Biopython mailing list  -  <a href="mailto:Biopython@biopython.org" target="_blank">Biopython@biopython.org</a><br>
<a href="https://mailman.open-bio.org/mailman/listinfo/biopython" rel="noreferrer" target="_blank">https://mailman.open-bio.org/mailman/listinfo/biopython</a><br>
</blockquote></div>
</blockquote></div>