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