[Biopython-dev] New documentation?

[Brian Osborne]

Peter,

In Bio/ I see 193 files with the “restructuredtext en” line, and 153 files without. Let’s get started with “step 1”. Will look at other directories as well ...

Brian O.



> On Oct 1, 2015, at 4:43 AM, Peter Cock <p.j.a.cock at googlemail.com> wrote:
> 
> 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