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

[hari jayaram]

Hi Peter..
Thanks for your comments. I could get a docset to build after all using
pydoctor.

The Dash.app is from Kapeli : http://kapeli.com/docsets
Its is very fast and works very well with the pydoctor generated docset.

For sphinx , I was using sphinx-apidoc with the "full" switch.

1) sphinx-apidoc -o apigenout -F Bio
2) In the apigenout directory I ran a "make html" to build the sphinx
documentation. This had some errors depending on the sphinx and python
version. This is also the step where it complained about Restriction.py
code. When I changed the code to get it to stop complaining. I think these
document creators do some kind of static analysis on the code..which may be
getting caught up in Restriction.py
3) Then you point the doc2dash application ( which uses beautifulsoup4 and
lxml) to build the docset ( from: https://github.com/hynek/doc2dash/)
doc2dash did not yeild a docset because of an infinite loop . I got some
help with it from Hynek Schlawack ..but in the end used pydoctor , which
worked.
doc2dash needs to be pointed to the directory where sphinx puts all the
html files. It automatically adds the docset to the Dash app
~/Library/Application\ Support/doc2dash directory

The commandline I used for doc2dash was .

doc2dash --name biopython -A html/


I have a working docset. If anyone wants to give it a go I can gladly share
it with you.

Thanks a tonne
Hari





On Sun, Oct 20, 2013 at 10:18 AM, Peter Cock <p.j.a.cock at googlemail.com>wrote:

> 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
>