Epydoc go boom

2009-09-14

tagged python, documentation, epydoc, tool

Making a good but abandoned documentation tool work.

So, epydoc used to be the neatest and bestest documentation tool available for Python. It produced documentation from introspecting code and thus was the easiest way to the most accurate API documentation. However, it looks like the project has been abandoned. Attempts to run it over code result in sometimes odd and cryptic failures:

% epydoc --html -o docs/api/html -v --debug qanda.validators ...
File /home/f0/paul/Projects/Py-qanda/qanda/validators.py, line 53,
in qanda.validators.BaseValidator.__call__
Warning: Lines 58, 59, 62: Improper paragraph indentation. ...

This improper indentation error seems to happen to me a lot. Fix it by forcing the documentation to be interpreted as restructured text on the commandline:

% epydoc --html -o docs/api/html -v --debug \
        --docformat=restructuredtext qanda.validators

or in the files themselves:

__docformat__ = "restructuredtext en"

If your documentation actually is in restructured text, that is. This may reveal the next level of bug:

% epydoc --html -o docs/api/html -v --docformat=restructuredtext \
        --debug qanda.validators
Traceback (most recent call last):
Parsing docstrings:
File "/home/f0/paul/Installed/bin/epydoc", line 5, in <module> pkg_resources.run_script('epydoc==3.0.1', 'epydoc')
...
File "/lib/python2.6/site-packages/epydoc-3.0.1-py2.6.egg/epydoc/markup/restructuredtext.py", line 307, in visit_paragraph
m = self._SUMMARY_RE.match(child.data)
AttributeError: 'Text' object has no attribute 'data'

The easy solution, as revealed on StackOverflow is to edit the offending line to catch the error:

# markup/restructuredtext.py, line 307
<   m = self._SUMMARY_RE.match(child.data)
---
>   try:
>      m = self._SUMMARY_RE.match(child.data)
>   except AttributeError:
>      m = None

And here's to hoping that someone picks up the project and modernizes it.

References

StackOverflow