[Biopython-dev] Docstrings

[Patrick Kunzmann]

I'd also vote for using numpydoc since it has a clear layout and it is 
well documented, so we do not have to write a docstring guideline 
ourselves.


Am 23.05.2017 um 14:15 schrieb 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