From 3db6c178e9c28df9e981fbf6239f112bdb8cddf4 Mon Sep 17 00:00:00 2001 From: Vladimir Rutsky Date: Mon, 6 Jun 2016 03:02:26 +0300 Subject: [PATCH] remove reference api documentation generation scripts Looks like some time ago API reference documentation was generated with Epydoc. Currently Epydoc project is not maintained (latest release was in 2008), and trying to build Buildbot docs fails with: ``` Traceback (most recent call last): File "apidocs/epyrun", line 202, in main() File "apidocs/epyrun", line 196, in main cli() File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/cli.py", line 965, in cli main(options, names) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/cli.py", line 757, in main exclude_parse=exclude_parse) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/docbuilder.py", line 275, in build_doc_index parse_docstring(val_doc, docindex, suppress_warnings) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/docstringparser.py", line 265, in parse_docstring api_doc.summary, api_doc.other_docs = api_doc.descr.summary() File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/markup/restructuredtext.py", line 179, in summary try: self._document.walk(visitor) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/docutils/nodes.py", line 138, in walk if child.walk(visitor): File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/docutils/nodes.py", line 130, in walk visitor.dispatch_visit(self) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit return method(node) File "/home/bob/stuff/buildbot/env/local/lib/python2.7/site-packages/epydoc/markup/restructuredtext.py", line 307, in visit_paragraph m = self._SUMMARY_RE.match(child.data) AttributeError: 'Text' object has no attribute 'data' ``` This can be workarounded by patching Epydoc with patches noted in common/generate_buildbot_api_documentation.sh (links are broken, but you can find them on the Internet). Tickets http://trac.buildbot.net/ticket/2087 and http://trac.buildbot.net/ticket/1839 refers to the process of migration docs from API generated to manually-written. AFAIK Epydoc reference documentation has not been published for the last few years. Though IMO autogenerated API docs is pretty good *addition* to manually written human-readable documentation, current Epydoc configuration is useless and only confuses. If we would like to have generated API reference we should investigate projects such as pydoctor, pdoc, or Sphinx API reference documenting utilities. --- .gitignore | 2 - Makefile | 6 +- apidocs/Makefile | 15 -- apidocs/epyrun | 202 ------------------ apidocs/gen-reference | 7 - common/generate_buildbot_api_documentation.sh | 21 -- 6 files changed, 1 insertion(+), 252 deletions(-) delete mode 100644 apidocs/Makefile delete mode 100644 apidocs/epyrun delete mode 100755 apidocs/gen-reference delete mode 100644 common/generate_buildbot_api_documentation.sh diff --git a/.gitignore b/.gitignore index cd7fd6582320..7220c5cae2be 100644 --- a/.gitignore +++ b/.gitignore @@ -31,8 +31,6 @@ master/docs/latest twisted/plugins/dropin.cache .coverage coverage-html -apidocs/reference -apidocs/reference.tgz master/docs/tutorial/_build _build # tox diff --git a/Makefile b/Makefile index 9b02f417b199..cf9b90490493 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # developer utilities -.PHONY: docs apidocs pylint flake8 +.PHONY: docs pylint flake8 PIP?=pip @@ -8,10 +8,6 @@ PIP?=pip docs: $(MAKE) -C master/docs -# create api documentation with epydoc -apidocs: - $(MAKE) -C apidocs - # pylint the whole sourcecode (validate.sh will do that as well, but only process the modified files) pylint: $(MAKE) -C master pylint; master_res=$$?; \ diff --git a/apidocs/Makefile b/apidocs/Makefile deleted file mode 100644 index 1d9554518f0b..000000000000 --- a/apidocs/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -.PHONY: all reference cleanpyc - -all: reference.tgz - -cleanpyc: - cd .. && find master slave -name '*.pyc' -exec rm \{} \; || exit 1 - -reference: cleanpyc - rm -rf reference - cd .. && python apidocs/epyrun -o apidocs/reference \ - --exclude="buildbot\\.test" --exclude="buildslave\\.test" \ - buildbot buildslave - -reference.tgz: reference - tar -zcf reference.tgz reference diff --git a/apidocs/epyrun b/apidocs/epyrun deleted file mode 100644 index 7358e370d70b..000000000000 --- a/apidocs/epyrun +++ /dev/null @@ -1,202 +0,0 @@ -#!/usr/bin/env python - -import sys -import os - -from twisted.python import reflect -from twisted.internet import reactor - -# epydoc -import epydoc -from epydoc.cli import cli - -if epydoc.__version__[0] == '2': - # Fix support for epydoc 2.x. Unneeded for 3.x - class FakeModule: - def __init__(self, name, level): - self.__level = level - self.__name__ = name - - def __repr__(self): - return '' % self.__name__ - __str__ = __repr__ - - def __nonzero__(self): - return 1 - - def __call__(self, *args, **kw): - pass #print 'Called:', args - - def __getattr__(self, attr): - if self.__level == 0: - raise AttributeError - return FakeModule(self.__name__+'.'+attr, self.__level-1) - - def __cmp__(self, other): - if not hasattr(other, '___name__'): - return -1 - return cmp(self.__name__, other.__name__) - - - def fakeOut(modname): - modpath = modname.split('.') - prevmod = None - for m in range(len(modpath)): - mp = '.'.join(modpath[:m+1]) - nm = FakeModule(mp, 4) - if prevmod: - setattr(prevmod, modpath[m], nm) - sys.modules[mp] = nm - prevmod = nm - - #fakeOut("twisted") - - # HACK: Another "only doc what we tell you". We don't want epydoc to - # automatically recurse into subdirectories: "twisted"'s presence was - # causing "twisted/test" to be docced, even thought we explicitly - # didn't put any twisted/test in our modnames. - - from epydoc import imports - orig_find_modules = imports.find_modules - - import re - - def find_modules(dirname): - if not os.path.isdir(dirname): return [] - found_init = 0 - modules = {} - dirs = [] - - # Search for directories & modules, and check for __init__.py. - # Don't include duplicates (like foo.py and foo.pyc), and give - # precedance to the .py files. - for file in os.listdir(dirname): - filepath = os.path.join(dirname, file) - if os.path.isdir(filepath): dirs.append(filepath) - elif not re.match(r'\w+.py.?', file): - continue # Ignore things like ".#foo.py" or "a-b.py" - elif file[-3:] == '.py': - modules[file] = os.path.join(dirname, file) - if file == '__init__.py': found_init = 1 - elif file[-4:-1] == '.py': - modules.setdefault(file[:-1], file) - if file[:-1] == '__init__.py': found_init = 1 - modules = modules.values() - - # If there was no __init__.py, then this isn't a package - # directory; return nothing. - if not found_init: return [] - - # Recurse to the child directories. - # **twisted** here's the change: commented next line out - #for d in dirs: modules += find_modules(d) - return modules - - imports.find_modules = find_modules - - -# Now, set up the list of modules for epydoc to document -modnames = [] -def addMod(arg, path, files): - for fn in files: - file = os.path.join(path, fn).replace('%s__init__'%os.sep, '') - if file.count('%stest%s' % (os.sep,os.sep)): continue - if file.count('%sbroken_test%s' % (os.sep,os.sep)): continue - if file[-3:] == '.py': - modName = file[:-3].replace(os.sep,'.') - try: - #print 'pre-loading', modName - reflect.namedModule(modName) - except ImportError, e: - print 'import error:', modName, e - except Exception, e: - print 'other error:', modName, e - else: - modnames.append(modName) - -def main(): - document_all = True # are we doing a full build? - names = ['buildbot/'] #default, may be overriden below - - #get list of modules/pkgs on cmd-line - try: - i = sys.argv.index("--modules") - except ValueError: - pass - else: - names = sys.argv[i+1:] - document_all = False - sys.argv[i:] = [] - #sanity check on names - for i in range(len(names)): - try: - j = names[i].rindex('buildbot/') - except ValueError: - raise SystemExit, 'You can only specify buildbot modules or packages' - else: - #strip off any leading directories before the 'twisted/' - #dir. this makes it easy to specify full paths, such as - #from TwistedEmacs - names[i] = names[i][j:] - - old_out_dir = "html" - #if -o was specified, we need to change it to point to a tmp dir - #otherwise add our own -o option - try: - i = sys.argv.index('-o') - old_out_dir = sys.argv[i+1] - try: - os.mkdir(tmp_dir) - except OSError: - pass - sys.argv[i+1] = tmp_dir - except ValueError: - sys.argv[1:1] = ['-o', tmp_dir] - - osrv = sys.argv - sys.argv=["IGNORE"] - - for name in names: - if name.endswith(".py"): - # turn it in to a python module name - name = name[:-3].replace(os.sep, ".") - try: - reflect.namedModule(name) - except ImportError: - print 'import error:', name - except Exception: - print 'other error:', name - else: - modnames.append(name) - else: #assume it's a dir - os.path.walk(name, addMod, None) - - sys.argv = osrv - - if 'buildbot.test' in modnames: - modnames.remove('buildbot.test') - if 'buildbot.broken_test' in modnames: - modnames.remove('buildbot.broken_test') - ##if 'twisted' in modnames: - ## modnames.remove('twisted') - - sys.argv.extend(modnames) - - import buildbot - - sys.argv[1:1] = [ - '-n', 'BuildBot %s' % buildbot.version, - '-u', 'http://buildbot.net/trac', '--no-private'] - - # Make it easy to profile epyrun - if 0: - import profile - profile.run('cli()', 'epyrun.prof') - else: - cli() - - print 'Done!' - - -if __name__ == '__main__': - main() diff --git a/apidocs/gen-reference b/apidocs/gen-reference deleted file mode 100755 index 473f77d5ebb8..000000000000 --- a/apidocs/gen-reference +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/bash -echo $(dirname $0) -cd $(dirname $0) -cd .. -find master slave -name '*.pyc' -exec rm \{} \; || exit 1 -# excludes both test suites -python docs/epyrun -o docs/reference --exclude="buildbot\\.test" --exclude="buildslave\\.test" buildbot buildslave diff --git a/common/generate_buildbot_api_documentation.sh b/common/generate_buildbot_api_documentation.sh deleted file mode 100644 index beb5df8588b6..000000000000 --- a/common/generate_buildbot_api_documentation.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/bin/bash - -cd /tmp -wget http://sourceforge.net/projects/epydoc/files/epydoc/3.0.1/epydoc-3.0.1.tar.gz -tar -xzf epydoc-3.0.1.tar.gz -cd epydoc-3.0.1 -wget http://gentoo-progress.googlecode.com/svn/overlays/progress/dev-python/epydoc/files/epydoc-3.0.1-docutils-0.6.patch -wget http://gentoo-progress.googlecode.com/svn/overlays/progress/dev-python/epydoc/files/epydoc-3.0.1-python-2.6.patch -patch -p0 < epydoc-3.0.1-docutils-0.6.patch -patch -p0 < epydoc-3.0.1-python-2.6.patch - -cd /tmp - -wget http://pypi.python.org/packages/source/b/buildbot/buildbot-0.8.7.tar.gz -wget http://pypi.python.org/packages/source/b/buildbot-slave/buildbot-slave-0.8.7.tar.gz -tar -xzf buildbot-0.8.7.tar.gz -tar -xzf buildbot-slave-0.8.7.tar.gz - -git clone https://github.com/buildbot/buildbot.git -cd buildbot/apidocs -PYTHONPATH="/tmp/epydoc-3.0.1:/tmp/buildbot-0.8.7:/tmp/buildbot-slave-0.8.7${PYTHONPATH:+:}${PYTHONPATH}" make