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

[Peter Cock]

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
>
>