[Biopython-dev] New documentation?

[Brian Osborne]

All,

This is done, and there’s a pull request for it.

Thanks again,

Brian O.


> On Oct 11, 2015, at 3:52 PM, Brian Osborne <bosborne11 at verizon.net> wrote:
> 
> 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
> 
> 
> _______________________________________________
> Biopython-dev mailing list
> Biopython-dev at mailman.open-bio.org
> http://mailman.open-bio.org/mailman/listinfo/biopython-dev