[Biopython-dev] sphinx build with github source has error in Restriction.py

[Peter Cock]

On Sat, Oct 19, 2013 at 12:43 AM, hari jayaram <harijay at gmail.com> wrote:
> Hi ,
> This is my first post here..so hope I am following the
> conventions/practices.

Welcome Hari,

> I am trying to create a Dash.app docset for biopython.  Dash.app is a very
> fast documentation browser , sadly for OSX alone.

This one http://kapeli.com/dash ?

> One way to getting a docset built is to point it at  sphinx documentation.
> I am using  the sphinx-apidoc to auto-generate the documentation ( ver
> Sphinx==1.2b3).
>
> Sphinx can generate the documentation just fine for most of the source
> tree.

How are you invoking Sphinx here? (i.e. what command line
so we can try to reproduce the problem locally)

> It has an issue with Restriction.py where it does not like cls.size.
> The  error is:
>
>   File
> "/Users/hari/.virtualenvs/pyvectormapdraw/lib/python2.7/site-packages/Bio/Restriction/Restriction.py",
> line 324, in __len__
>     return cls.size
> AttributeError: type object 'RestrictionType' has no attribute 'size'
>
> I could cheat..and change it to "return 1" in the code and I got the
> documentation to build just fine.

The RestrictionType.__init__ documentation warns it is not
intended for direct use (see the auto-generated file
Restriction_Dictionary.py and associated magic to create
a class for each enzyme). It seems Sphinx is trying to call
the methods of the class.

> I dont know why sphinx cares about that line to throw an error ,
> or how to get around that without cheating.

I'm not sure either - there must be other strange Python
classes where __len__ doesn't work without special
initialisation. That might be worth asking on the Sphinx
mailing list?

> Thanks
> Hari
>
> On a side note: The sphinx documentation , looks fine in a browser , but
> the dash2doc app could not index it to yield a docset. The problem was
> somehwere in the html , beautiful soup entered an infinite loop.

Could be a bug in the HTML output from sphinx, perhaps a
malformed tag from an unusual string in our comments?

> I could however use pydoctor to generate a docset. It seems
> to work OK..but while sphinx doc created 15,804 index entries.
> The pydoctor index had only around 5000 entries.
>
> Ref: http://kapeli.com/docsets

I don't know if those numbers should be the same, or if one
counts modules while the other counts classes/functions etc?

Peter

P.S.

The HTML API docs we distribute are generated with epydoc,
see http://biopython.org/wiki/Building_a_release