[Biopython-dev] New documentation?

[Peter Cock]

Hi Brian,

You mean: http://biopython.org/wiki/Active_projects

We're still only part way though step one, converting the
docstrings (documentation comments within the code itself)
to use reStructuredText markup rather than plain text or
the niche epydoc format.

Any of our Python files with this magic line are done:

__docformat__ = "restructuredtext en"

If there is no __docformat__ line or it is set to something
else, then it is ripe for reformatting. Anyone could fork
Biopython on GitHub, start a branch and begin committing
changes on a file by file basis - using grep etc to find
modules not yet tackled.

For now we're still using epydoc to process the docstrings
into HTML which you can view from the last release here:
http://biopython.org/DIST/docs/api/

e.g. This is currently done using reStructuredText so the
doctest examples (lines starting >>>) are nicely coloured:
http://biopython.org/DIST/docs/api/Bio.SeqIO-module.html

You would need epydoc installed to visually check your
conversion.

You'll likely find many of the remaining modules are quite
lacking in documentation - writing more would be a bonus.

If you like writing doctests (which is tricky to do for cross
platform testing), they would be enabled in run_tests.py

------------------------------------------------------------

Step two would be looking at replacing epydoc with Sphinx
for producing a web-friendly version of the docstrings.
We likely have enough done now that this might be worth
trying already....

Peter

On Wed, Sep 30, 2015 at 6:18 PM, Brian Osborne <bosborne11 at verizon.net> wrote:
> All,
>
> At biopython.org I read that there’s a project on documentation, Porting
> Biopython documentation to Sphinx.
>
> Is this still the case? If so, how do I get involved, and where are the
> files?
>
> Thanks again,
>
> Brian O.
>
> _______________________________________________
> Biopython-dev mailing list
> Biopython-dev at mailman.open-bio.org
> http://mailman.open-bio.org/mailman/listinfo/biopython-dev