[Biopython] [Biopython-dev] Good progress on replacing epydoc with Sphinx for API docs

[Peter Cock]

With Sphinx 1.8.0 out now which supports the extra
configuration I wanted for showing special class
methods, I've made a cleaned up pull request:

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

Eyeballing the output there seems to be a glitch with
the method table layout, and it needs fine tuning
for things like page width - but this is progress.

Peter
On Wed, Nov 15, 2017 at 4:22 PM Peter Cock <p.j.a.cock at googlemail.com> wrote:
>
> Hello all,
>
> The mailing list is still currently being unreliable, see:
>
> http://mailman.open-bio.org/pipermail/biopython-dev/2017-November/021890.html
>
> I didn't get Adam's message (below) directly in my inbox, but
> saw it on the archive:
>
> http://mailman.open-bio.org/pipermail/biopython-dev/2017-November/021889.html
>
> I'm taking this as another vote on top of Sourav's to have both
> the epydoc and sphinx versions of the API documentation for
> Biopython 1.71 (and potentially longer than that if issues are
> identified with the Sphinx version which take time to resolve).
>
> As Adam's question about the formatting of the docstring content
> itself, we're using reStructuredText markup, which both epydoc and
> sphinx-apidoc will render in broadly the same way. I have made
> minor docstring changes on the sphinx branch, but these are fairly
> trivial things like using numpdoc standardised section names - there
> is nothing which I expect to cause epydoc any trouble.
>
> Thank you for your comments,
>
> Peter
>
> On Sun Nov 12 13:58:12 UTC 2017, Adam Kurkiewicz wrote:
> >
> > I generally really liked epydoc, and used biopython's epydoc quite a few
> > times. It's a very big shame it's no longer in active development.
> >
> > That being said, I think staying up to date with modern tooling is
> > important, so it's a good decision we'll be using sphinx now.
> >
> > How much effort would it be to let epydoc stay around for a little bit,
> > at least to be able to quickly compare sphinx and epydoc output?
> >
> > If there are significant efforts (possibly automated) to change the
> > meta-language of underlying pydoc comments, than maybe it's not worth
> > keeping both. We could always have a snapshot of historical epydoc
> > hidden somewhere with a big warning "this documentation is obsolete and
> > may not represent actual functionality", and then we could quickly
> > compare things, at least until both documentations significantly
> > diverge.
> >
> > Adam
> >
> > On Thu, Nov 2, 2017 at 2:55 AM, Peter Cock <p.j.a.cock at googlemail.com>
> > wrote:
> >>
> >> Dear Biopythoneers,
> >>
> >> For those not subscribed to GitHub alerts, I wanted to mention
> >> I have made good progress on building the Biopython API
> >> documentation (drawing on our reStructuredText formatted
> >> docstrings) using sphinx-apidoc instead of epydoc. See:
> >>
> >> https://github.com/biopython/biopython/issues/906
> >> https://github.com/biopython/biopython/pull/1388
> >>
> >> (The tool epydoc is no longer maintained, and the HTML
> >> it produces is quite old fashioned with no search support
> >> etc).
> >>
> >> I'm hoping we can use this for Biopython 1.71, our next
> >> release.
> >>
> >> Do people have any strong preference between:
> >>
> >> - Having both epydoc and sphinx versions online at
> >>   the same time (at least in the short term, useful for
> >>   comparison and identifying any regressions).
> >>
> >> - Dropping epydoc, replacing its old HTML pages with
> >>   redirects to sphinx equivalent pages.
> >>
> >> Also, do people have any strong preference between
> >> continuing to host the API docs under biopython.org
> >> (using GitHub Pages) versus using a third party site
> >> like readthedocs.org (or both)?
> >>
> >> Either way, we can likely keep a copy of the docs for
> >> each Biopython release online for historical reference.
> >>
> >> Thanks,
> >>
> >> Peter
> >> _______________________________________________
> >> Biopython-dev mailing list
> >> Biopython-dev at mailman.open-bio.org
> >> http://mailman.open-bio.org/mailman/listinfo/biopython-dev
> >
> >