[Biopython-dev] New documentation?

[Peter Cock]

Thanks Brian,

https://github.com/biopython/biopython/pull/646

Since this really needs lots of eyes on it to manually review
the HTML output, I'll try to run epydoc on the branch this
week, and post it online next to the current release files:

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

I'll post the temp URL here and on the pull request to solicit
any markup corrections (reporting other things like typos
too would be welcome).

Peter

On Sun, Oct 25, 2015 at 6:21 PM, Brian Osborne <bosborne11 at verizon.net> wrote:
> 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
>