[Biopython] Attempting to automatically publish the Sphinx API documentation

[Peter Cock]

Dear Biopythoneers,

Progress - I have got a working prototype, extending the TravisCI
job which already built the API documentation, to also deploy it
to a documentation GitHub pages repository:

https://github.com/biopython/biopython/pull/2172

You can view the results here, although don't be too surprised
if the content vanishes at intervals with a 404 error while things
are reset for testing. Also, the URL scheme is not yet confirmed:

New: https://biopython.org/docs/dev/api/ (to be confirmed)
Old: https://biopython.org/DIST/docs/api/

I am thinking to have both versions live for the Biopython 1.74
release, and thereafter have a redirection setup.

I'll soon be asking everyone to help proof read the new version
for layout issues (and other docstring problems too).

If anyone has strong views on using biopython.org (which is on
GitHub pages) versus external hosting on Read-The-Docs, now
would be a good time to speak up.

Thanks,

Peter

On Fri, Jun 14, 2019 at 4:51 PM Peter Cock <p.j.a.cock at googlemail.com> wrote:
>
> Dear Biopythoneers,
>
> Some of you will have noticed a new (currently almost empty)
> repository appeared, https://github.com/biopython/docs
>
> One of many things we've been trying to do in Biopython is replace
> the ugly but functional API documentation generated with epydoc
> (an old tool which is no longer actively developed) with something
> more modern (and supported) like Sphinx autodoc.
>
> The goal here is to extend the existing TravisCI job which extracts
> our API documentation as RST and turns it into HTML using Sphinx
> autodoc, by deploying the files to https://github.com/biopython/docs
> using https://github.com/drdoctr/doctr
>
> The HTML output could then be published directly via GitHub
> Pages (similar to how we already host biopython.org), and/or
> we could point Read The Docs at the generated RST.
>
> This could then be extended to handle an RST version of the
> Tutorial, and again make it into HTML using Sphinx rather than
> hevea (another old tool which is no longer actively developed).
>
> Peter
>
> See also:
>
> http://biopython.org/DIST/docs/api/
> https://github.com/biopython/biopython/issues/906
> https://github.com/biopython/biopython/issues/907