[Biopython-dev] Docstrings

[Peter Cock]

Yes, and since Biopython 1.67 already assume reStructuredText
when epydoc is run as per:

http://biopython.org/wiki/Building_a_release

This renders the HTML markup shown here - and does have
some content where the markup failed:

http://biopython.org/DIST/docs/api/

There is a recent tracking issue for addressing invalid RST in
the current docstrings - the absence of a suitable linting tool
is a hinderance here, I link to a proof of principle on this issue:

https://github.com/biopython/biopython/issues/1221

Note Python PEP287 recommends using RST for docstrings:

https://www.python.org/dev/peps/pep-0287/

Beyond that we have talked of agreeing a standard template
for the docstrings (e.g. listing function arguments, return values,
or class attributes), perhaps following a (simplification) of the
NumPy model:

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

I'd like to replace epydoc with something being maintained and
able to produce prettier output:

https://github.com/biopython/biopython/issues/906

Peter

On Tue, May 23, 2017 at 11:21 AM, Patrick Kunzmann
<padix.kleber at gmail.com> wrote:
> Hello people,
>
> the Biopython website states, it is planned to migrate the docstrings to
> "reStructuredText Markup". Now I would like to know, if this infomration is
> still up to date.
>
> Best regards,
>
> Patrick
>
> _______________________________________________
> Biopython-dev mailing list
> Biopython-dev at mailman.open-bio.org
> http://mailman.open-bio.org/mailman/listinfo/biopython-dev