import py import sys WIDTH = 75 plugins = [ ('plugins for Python test functions', 'xfail figleaf monkeypatch capture recwarn',), ('plugins for other testing styles and languages', 'oejskit unittest nose doctest restdoc'), ('plugins for generic reporting and failure logging', 'pastebin resultlog terminal',), ('plugins for generic reporting and failure logging', 'pastebin resultlog terminal',), ('misc plugins / core functionality', 'helpconfig pdb keyword hooklog') #('internal plugins / core functionality', # #'pdb keyword hooklog runner execnetcleanup # pytester', # 'pdb keyword hooklog runner execnetcleanup' # pytester', #) ] externals = { 'oejskit': 'run javascript tests in real life browsers', } def warn(*args): msg = " ".join(map(str, args)) print >>sys.stderr, "WARN:", msg class RestWriter: _all_links = {} def __init__(self, target): self.target = py.path.local(target) self.links = [] def _getmsg(self, args): return " ".join(map(str, args)) def Print(self, *args, **kwargs): msg = self._getmsg(args) if 'indent' in kwargs: indent = kwargs['indent'] * " " lines = [(indent + x) for x in msg.split("\n")] msg = "\n".join(lines) self.out.write(msg) if not msg or msg[-1] != "\n": self.out.write("\n") self.out.flush() def sourcecode(self, source): lines = str(source).split("\n") self.Print(".. sourcecode:: python") self.Print() for line in lines: self.Print(" ", line) def _sep(self, separator, args): msg = self._getmsg(args) sep = len(msg) * separator self.Print() self.Print(msg) self.Print(sep) self.Print() def h1(self, *args): self._sep('=', args) def h2(self, *args): self._sep('-', args) def h3(self, *args): self._sep('+', args) def li(self, *args): msg = self._getmsg(args) sep = "* %s" %(msg) self.Print(sep) def dt(self, term): self.Print("``%s``" % term) def dd(self, doc): self.Print(doc, indent=4) def para(self, *args): msg = self._getmsg(args) self.Print(msg) def add_internal_link(self, name, path): relpath = path.new(ext=".html").relto(self.target.dirpath()) self.links.append((name, relpath)) def write_links(self): self.Print() self.Print(".. include:: links.txt") for link in self.links: key = link[0] if key in self._all_links: assert self._all_links[key] == link[1], (key, link[1]) else: self._all_links[key] = link[1] def write_all_links(cls, linkpath): p = linkpath.new(basename="links.txt") p_writer = RestWriter(p) p_writer.out = p_writer.target.open("w") for name, value in cls._all_links.items(): p_writer.Print(".. _`%s`: %s" % (name, value)) p_writer.out.close() del p_writer.out write_all_links = classmethod(write_all_links) def make(self, **kwargs): self.out = self.target.open("w") self.makerest(**kwargs) self.write_links() self.out.close() print "wrote", self.target del self.out class PluginOverview(RestWriter): def makerest(self, config): plugindir = py.path.local(py.__file__).dirpath("test", "plugin") for cat, specs in plugins: pluginlist = specs.split() self.h1(cat) for name in pluginlist: oneliner = externals.get(name, None) docpath = self.target.dirpath(name).new(ext=".txt") if oneliner is not None: htmlpath = docpath.new(ext='.html') self.para("%s_ %s" %(name, oneliner)) self.add_internal_link(name, htmlpath) else: doc = PluginDoc(docpath) doc.make(config=config, name=name) self.add_internal_link(name, doc.target) self.para("%s_ %s" %(name, doc.oneliner)) self.Print() class HookSpec(RestWriter): def makerest(self, config): module = config.pluginmanager.hook._hookspecs source = py.code.Source(module) self.h1("hook specification sourcecode") self.sourcecode(source) class PluginDoc(RestWriter): def makerest(self, config, name): config.pluginmanager.import_plugin(name) plugin = config.pluginmanager.getplugin(name) assert plugin is not None, plugin doc = plugin.__doc__.strip() i = doc.find("\n") if i == -1: oneliner = doc moduledoc = "" else: oneliner = doc[:i].strip() moduledoc = doc[i+1:].strip() self.name = plugin.__name__.split(".")[-1] self.oneliner = oneliner self.moduledoc = moduledoc self.h1("%s plugin" % self.name) # : %s" %(self.name, self.oneliner)) self.Print(self.oneliner) self.Print() self.Print(".. contents::") self.Print(" :local:") self.Print() self.Print(moduledoc) self.emit_funcargs(plugin) self.emit_options(plugin) self.emit_source(plugin, config.hg_changeset) #self.sourcelink = (purename, # "http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/" + # purename + ".py") # def emit_source(self, plugin, hg_changeset): basename = py.path.local(plugin.__file__).basename if basename.endswith("pyc"): basename = basename[:-1] #self.para("`%s`_ source code" % basename) #self.links.append((basename, # "http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/" + # basename)) self.h1("Start improving this plugin in 30 seconds") self.para(py.code.Source(""" 1. Download `%s`_ plugin source code 2. put it somewhere as ``%s`` into your import path 3. a subsequent ``py.test`` run will use your local version Checkout customize_, other plugins_ or `get in contact`_. """ % (basename, basename))) # your work appreciated if you offer back your version. In this case # it probably makes sense if you `checkout the py.test # development version`_ and apply your changes to the plugin # version in there. #self.links.append((basename, # "http://bitbucket.org/hpk42/py-trunk/raw/%s/" # "py/test/plugin/%s" %(hg_changeset, basename))) self.links.append((basename, "http://bitbucket.org/hpk42/py-trunk/raw/%s/" "py/test/plugin/%s" %(pyversion, basename))) self.links.append(('customize', '../customize.html')) self.links.append(('plugins', 'index.html')) self.links.append(('get in contact', '../../contact.html')) self.links.append(('checkout the py.test development version', '../../download.html#checkout')) if 0: # this breaks the page layout and makes large doc files #self.h2("plugin source code") self.Print() self.para("For your convenience here is also an inlined version " "of ``%s``:" %basename) #self(or copy-paste from below) self.Print() self.sourcecode(py.code.Source(plugin)) def emit_funcargs(self, plugin): funcargfuncs = [] prefix = "pytest_funcarg__" for name in vars(plugin): if name.startswith(prefix): funcargfuncs.append(getattr(plugin, name)) if not funcargfuncs: return for func in funcargfuncs: argname = func.__name__[len(prefix):] self.Print() self.Print(".. _`%s funcarg`:" % argname) self.Print() self.h2("the %r test function argument" % argname) if func.__doc__: doclines = func.__doc__.split("\n") source = py.code.Source("\n".join(doclines[1:])) source.lines.insert(0, doclines[0]) self.para(str(source)) else: self.para("XXX missing docstring") warn("missing docstring", func) def emit_options(self, plugin): from py.__.test.parseopt import Parser options = [] parser = Parser(processopt=options.append) if hasattr(plugin, 'pytest_addoption'): plugin.pytest_addoption(parser) if not options: return self.h2("command line options") self.Print() formatter = py.compat.optparse.IndentedHelpFormatter() for opt in options: switches = formatter.format_option_strings(opt) self.Print("``%s``" % switches) self.Print(opt.help, indent=4) if __name__ == "__main__": _config = py.test.config _config.parse([]) _config.pluginmanager.do_configure(_config) pydir = py.path.local(py.__file__).dirpath() pyversion = py.version cmd = "hg tip --template '{node}'" old = pydir.dirpath().chdir() _config.hg_changeset = py.process.cmdexec(cmd).strip() testdir = pydir.dirpath("doc", 'test') ov = PluginOverview(testdir.join("plugin", "index.txt")) ov.make(config=_config) ov = HookSpec(testdir.join("plugin", "hookspec.txt")) ov.make(config=_config) RestWriter.write_all_links(testdir.join("plugin", "links.txt"))