[Biopython-dev] Documentation Status

[Travis Wrightsman]

Thank you for the introduction!

It looks like the Align/Applications package is mostly in epydocs format.
I'll see what work I can do to convert the docstrings into reStructuredText
module by module or file by file.

I will also see if I can install the Sphinx compiler on my linux server and
test the output as I go along. Are both Sphinx and Epydocs compatible with
both reStructuredText and epydocs format?

Cheers,
Travis

On Mon, Oct 13, 2014 at 8:14 AM, Peter Cock <p.j.a.cock at googlemail.com>
wrote:

> On Mon, Oct 13, 2014 at 3:52 PM, Travis Wrightsman <twrig002 at ucr.edu>
> wrote:
> > Looking to make contributions to BioPython and I figured the
> documentation
> > would be a good place to start. The "What's being worked on" page hasn't
> > been updated in a few months and the link to the Sphinx documentation
> > feature request on redmine.open-bio.org is giving me a Ruby error.
>
> Bah. That might be related to a forced update of the OS due to the
> recent "shellshock" bash security problem. I'll raise that on our
> volunteer SysAdmin's mailing list, root-l
> http://mailman.open-bio.org/mailman/listinfo/root-l
>
> > Is the documentation port a feature that we would still like to complete
> or
> > should I look to making contributions to the code?
>
> The short term goal was to get the Python docstrings (in the code)
> using restructuredtext markup (while for now continuing to build
> the API documentation using epydoc), once that is done we can
> try to build the API documentation using SPhinx.
>
> See http://biopython.org/DIST/docs/api/
>
> Note that in order to maintain the plain text side of things, like
> the NumPy project we're not exploiting the full potential of
> the markup language features (less is more).
>
> (Moving the Tutorial from LaTeX to SPhinx is a rather different
> question, where we did not have a consensus. More recently,
> Tiago has been advocating using IPython notebooks instead
> for example.)
>
> Right now some of the docstrings use epydoc markup which is
> similar, but the majority are simply plain text. Try:
>
> $ grep __docformat__ Bio/*.py Bio/*/*.py Bio/*/*/*.py BioSQL*.py
> Bio/Seq.py:__docformat__ = "epytext en"  # Don't just use plain text
> in epydoc API pages!
> Bio/SeqRecord.py:__docformat__ = "epytext en"  # Simple markup to show
> doctests nicely
> Bio/__init__.py:__docformat__ = "epytext en"  # not just plaintext
> Bio/Align/Generic.py:__docformat__ = "epytext en"  # Don't just use
> plain text in epydoc API pages!
> Bio/Align/__init__.py:__docformat__ = "epytext en"  # Don't just use
> plain text in epydoc API pages!
> Bio/AlignIO/StockholmIO.py:__docformat__ = "epytext en"  # not just
> plaintext
> Bio/AlignIO/__init__.py:__docformat__ = "epytext en"  # not just plaintext
> Bio/CodonAlign/CodonAlignment.py:__docformat__ = "epytext en"  # Don't
> just use plain text in epydoc API pages!
> Bio/CodonAlign/CodonAlphabet.py:__docformat__ = "epytext en"  # Don't
> just use plain text in epydoc API pages!
> Bio/CodonAlign/CodonSeq.py:__docformat__ = "epytext en"  # Don't just
> use plain text in epydoc API pages!
> Bio/CodonAlign/__init__.py:__docformat__ = "epytext en"  # Don't just
> use plain text in epydoc API pages!
> Bio/NMR/NOEtools.py:__docformat__ = "restructuredtext en"
> Bio/NMR/xpktools.py:__docformat__ = "restructuredtext en"
> Bio/PDB/DSSP.py:__docformat__ = "epytext en"
> ...
>
> Those already using epytext should be easy enough to convert
> and proof read for visual layout after running though epydoc.
> e.g. http://biopython.org/DIST/docs/api/Bio.SeqIO-module.html
>
> However, the majority of our code is still essentially not using
> any markup for the docstrings.
>
> Also note that we test doctests via Tests/run_tests.py
>
> So I would suggest picking a submodule that interests you,
> and having a look at the existing documentation - which may
> be quite sparse and need writing, or may just need some
> light reformatting. Then get epydoc installed and working,
> and check the HTML rendered output before/after your
> changes.
>
> If you you have queries, please ask here. Once you have
> some useful changes, commit them (maybe file by file, or
> module by module) and raise a pull request :)
>
> Regards,
>
> Peter
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.open-bio.org/pipermail/biopython-dev/attachments/20141013/ea0af520/attachment.html>