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

[Adam Kurkiewicz]

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 Wed, Nov 1, 2017, at 09:25 PM, Peter Cock 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