[Biopython-dev] epydoc formatting in Bio.Phylo

[Peter]

Hi Eric,

One of the tasks in building a release which I am only doing now is
updating the API docs:
http://biopython.org/wiki/Building_a_release

Using epydoc can raise warnings about errors in the code (usually
things like broken imports) which means it doubles as a code check.
The code news is I don't see any such issues (beyond existing name
shadowing which we are stuck with).

However, this has flagged a few things in Bio.Phylo, most of which
look like documentation formatting issues since you have explicitly
stated you are using the epydoc markup with:

__docformat__ = "epytext en"

+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/BaseTree.py,
line 671, in
| Bio.Phylo.BaseTree.Subtree
|   Warning: @param for unknown parameter "label"
|
+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/BaseTree.py,
line 507, in
| Bio.Phylo.BaseTree.TreeMixin.prune
|   Warning: Line 513: Possible mal-formatted field item.
|
+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/Newick.py, line 255, in
| Bio.Phylo.Newick._TreeShim.root_with_outgroup
|   Warning: Line 258: Improper paragraph indentation.
|
+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/PhyloXML.py,
line 117, in
| Bio.Phylo.PhyloXML.Phylogeny
|   Warning: @param for unknown parameter "clade"
|
+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/_utils.py, line 224, in
| Bio.Phylo._utils.draw_ascii
|   Warning: Lines 228, 229, 230, 231, 232, 233, 234: Improper
paragraph indentation.
|
+------------------------------------------------------------------------------------------------------
| File /usr/local/lib/python2.6/dist-packages/Bio/Phylo/_utils.py, line 132, in
| Bio.Phylo._utils.draw_graphviz
|   Warning: Lines 159, 164, 176, 179: Fields must be the final
elements in an epytext string.
|   Warning: Line 179: Improper paragraph indentation.
|

Another to-do item before Biopython 1.54 final.

Peter