test_ok1/bin-for-dist/makepluginlist.py

import os, sys
WIDTH = 75

plugins = [
    ('plugins for Python test functions', 
            'skipping figleaf monkeypatch capture recwarn',),
    ('plugins for other testing styles and languages', 
            'oejskit unittest nose django 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 mark 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",
    'django': "support for testing django applications", 
#    'coverage': "support for using Ned's coverage module", 
#    'xmlresult': "support for generating xml reports "
#            "and CruiseControl integration",
}

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.std.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__":
    if os.path.exists("py"):
        sys.path.insert(0, os.getcwd())
    import py
    _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"))