Epydoc go boom
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.