Last modified: 2014-11-19 21:24:17 UTC
epydoc documentation was broken with the introduction of ModuleDeprecationWrapper in __init__. $ epydoc --debug pywikibot Warning: Module pywikibot is shadowed by a variable with the same name. Traceback (most recent call last): Progress: 28:32 File "/usr/bin/epydoc", line 13, in <module>-----------------------------------------------------------------------------------------------] cli() Building documentation: pywikibot'.i18n (.../pywikibot/i18n.pyc) File "/usr/lib/python2.7/dist-packages/epydoc/cli.py", line 965, in cli main(options, names) File "/usr/lib/python2.7/dist-packages/epydoc/cli.py", line 757, in main exclude_parse=exclude_parse) File "/usr/lib/python2.7/dist-packages/epydoc/docbuilder.py", line 206, in build_doc_index doc_pairs = _get_docs_from_items(items, options) File "/usr/lib/python2.7/dist-packages/epydoc/docbuilder.py", line 398, in _get_docs_from_items item, doc_pairs[-1], options, progress_estimator) File "/usr/lib/python2.7/dist-packages/epydoc/docbuilder.py", line 595, in _get_docs_from_submodules module_filename, options, progress_estimator, pkg_docs) File "/usr/lib/python2.7/dist-packages/epydoc/docbuilder.py", line 541, in _get_docs_from_module_file filename=filename, context=parent_docs[0]) File "/usr/lib/python2.7/dist-packages/epydoc/docintrospecter.py", line 106, in introspect_docs value = get_value_from_filename(filename, context) File "/usr/lib/python2.7/dist-packages/epydoc/docintrospecter.py", line 828, in get_value_from_filename pkg_dir = os.path.split(context.filename)[0] AttributeError: 'GenericValueDoc' object has no attribute 'filename' removing the last two lines of __init__.py fixes that problem, but likely others exist; here is the output after that is removed, showing mostly a problem with the deprecators/redirectors. $ epydoc --debug pywikibot +------------------------------------------------------------------------------------------------------------------------------------------- | In .../pywikibot/botirc.py: | Import failed (but source code parsing was successful). | Error: ImportError: No module named ircbot (line 23) | Warning: No information available for pywikibot.data.api.CTEBinaryBytesGenerator's base email.generator.BytesGenerator Warning: No information available for pywikibot.data.api.CTEBinaryMIMEMultipart's base email.mime.multipart.MIMEMultipart Warning: No information available for pywikibot.data.api.CTEBinaryBytesGenerator's base email.generator.BytesGenerator Warning: No information available for pywikibot.data.api.CTEBinaryMIMEMultipart's base email.mime.multipart.MIMEMultipart Debug: <RoutineDoc pywikibot.categoryFormat> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.compileLinkR> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.extract_templates_and_params> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.getCategoryLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.getLanguageLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.interwikiFormat> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.interwikiSort> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.isDisabled> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeCategoryLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeCategoryLinksAndSeparator> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeDisabledParts> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeHTMLParts> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeLanguageLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.removeLanguageLinksAndSeparator> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.replaceCategoryInPlace> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.replaceCategoryLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.replaceExcept> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.replaceLanguageLinks> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.unescape> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.site.APISite.forceLogin> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.site.BaseSite.getNamespaceIndex> is in <ModuleDoc pywikibot.tools> but name does not dominate Debug: <RoutineDoc pywikibot.site.BaseSite.normalizeNamespace> is in <ModuleDoc pywikibot.tools> but name does not dominate Warning: 304 markup errors were found while processing docstrings. Use the verbose switch (-v) to display markup errors.
Change 169788 had a related patch set uploaded by John Vandenberg: Detect epydoc and disable decorators, etc https://gerrit.wikimedia.org/r/169788
Change 169985 had a related patch set uploaded by John Vandenberg: Epydoc syntax issues https://gerrit.wikimedia.org/r/169985
One rather annoying warning is @return on property getters. See http://sourceforge.net/p/epydoc/bugs/290/
Looking for an alternative to the unmaintained epydoc, I came across pydoctor. https://bugs.launchpad.net/pydoctor I've found one bug that makes our output look a bit silly. https://bugs.launchpad.net/pydoctor/+bug/1393776
Change 169788 merged by jenkins-bot: Disable decorators and wrappers when not __debug__ https://gerrit.wikimedia.org/r/169788
It is still not ideal.
An old version of the patch contains a way to detect epydoc https://gerrit.wikimedia.org/r/#/c/169788/6/pywikibot/tools.py,cm However that is an quite expensive task to run during startup. If we can get Sphinx doc builds to work easily, I think we can live with epydoc being difficult to run.
