Documentation script of Python interface fails on Mac OS X

[Tamás Nepusz]

interfaces/python/scripts/mkdoc.sh throws an exception with Epydoc 3.0.1. on Mac OS X.

[Tamás Nepusz (ntamas)]

Apparently this is a bug in Epydoc:

http://sourceforge.net/tracker/index.php?func=detail&aid=3293380&group_id=32455&atid=405618

The fix mentioned at the above link works for me. I'll try to figure out whether there is a workaround that does not involve patching Epydoc.

The strangest thing is that Epydoc 3.0.1 works perfectly fine for me on Linux, but the same version fails on Mac OS X.

[Tamás Nepusz (ntamas)]

Further research revealed that the Debian/Ubuntu package for Epydoc uses the following patch to work around the issue:

http://sourceforge.net/tracker/?func=detail&aid=3027939&group_id=32455&atid=405620

According to the patch, docutils >=0.6 and Epydoc 3.0.1 are not playing together too nicely.

[Tamás Nepusz (ntamas)]

Monkey-patched docutils on-the-fly to make things work on Mac OS X. See the following commit:

http://bazaar.launchpad.net/~igraph/igraph/0.6-main/revision/2627

The bottom line is that you should update the source tree and use the new scripts/mkdoc.sh -- hopefully this will make things work.

[h0cked (timobj)]

The patch works great for generating the html api doc.
You might want to know that I am getting this error when generating the pdf document.
pdflatex failed: Missing } inserted.
         <inserted text>
                         }
         l.574 value={None}}
                                %
         ?

Thanks! Great work!

[Tamás Nepusz (ntamas)]

Can you please upload the contents of all the .tex files that were generated by epydoc in doc/api/pdf? (You can add attachments to this bug report using the "Add attachment or patch" button below).

[h0cked (timobj)]

Attached.
Generated using:
<code>
./epydoc-patched --debug --latex -o ${DOC_API_FOLDER}/pdf --exclude=igraph.test --inheritance=listed -v --name="IGraph library" --url="http://igraph.sourceforge.net" $PACKAGES
</code>
My pdflatex came form fink as well
i texlive 0.20100722- Bundle package for TeX Live
 i texlive-base 0.20100722- Base programs for a TeX Live installation

Thanks!

[Tamás Nepusz (ntamas)]

Hmm, this is really weird again - I was wondering whether these are really the latest .tex files. Most of the igraph classes are not documented in these; I have at least 10 extra .tex files like "igraph._igraph-module.tex". On the other hand, my Epydoc does not seem to produce a .tex file for each separate class; there is only one .tex file per module. I have a "--separate-classes" command line option for Epydoc which would separate each class into a .tex file, but I did not use that and seemingly neither did you.

How did you install Epydoc on your machine? I was simply using "pip install epydoc".

[h0cked (timobj)]

I am on Mac OS X Lion, using "fink install epydoc-py27" to install epydoc.

Actually, I found the issue. In /interfaces/python/igraph/_init_.py
line 751: U{http://arxiv.org/abs/cond-mat/0311416.
Missing "}" at the end, so I just changed it to
U{http://arxiv.org/abs/cond-mat/0311416}.

Rerun ./mkdoc, it works perfectly now.

Thanks!

[Tamás Nepusz (ntamas)]

Thanks, glad that it worked! I'll add the missing closing brace and close the bug.

[Tamás Nepusz (ntamas)]

Patch committed in trunk/#2630.

[Gábor Csárdi (gabor.csardi)]

The development of igraph has moved to github, so please do not comment on this bug here. You are of course welcome to comment on github, here:
https://github.com/igraph/igraph/issues/95