[Biopython-dev] Documentation Status

[Peter Cock]

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