Cleaned up mkwiki and mkdocs somewhat

2 files changed, 199 insertions, 184 deletions

diff --git a/scripts/mkdocs.py b/scripts/mkdocs.py
index 74d9e2b..65c85bb 100755
--- a/scripts/mkdocs.py
+++ b/scripts/mkdocs.py
@@ -7,7 +7,6 @@ from docutils.core import publish_string, publish_parts
 from docutils.readers.standalone import Reader
 from docutils.writers.html4css1 import Writer, HTMLTranslator
 from pudge.browser import Browser
-from epydoc.objdoc import _lookup_class_field
 import inspect
 import nose
 import textwrap
@@ -22,6 +21,7 @@ remove_at = re.compile(r' at 0x[0-9a-f]+')
 
 
 def defining_class(cls, attr):
+    from epydoc.objdoc import _lookup_class_field
     val, container = _lookup_class_field(cls, attr)
     return container.value()
 
@@ -363,185 +363,188 @@ def document_rst_test(filename, section):
                      tpl,
                      parts))
 
-root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
-doc = os.path.join(root, 'doc')
-tpl = open(os.path.join(doc, 'doc.html.tpl'), 'r').read()
-api_tpl = open(os.path.join(doc, 'plugin_api.html.tpl'), 'r').read()
-plug_tpl = open(os.path.join(doc, 'plugin.html.tpl'), 'r').read()
-std_info = {
-    'version': nose.__version__,
-    'date': time.ctime()
-    }
-to_write = []
-
-
-# plugins
-from nose import plugins
-from nose.plugins.base import IPluginInterface
-from nose.plugins import errorclass
-
-# writing plugins guide
-writing_plugins = {'body': to_html(plugins.__doc__)}
-writing_plugins.update(std_info)
-writing_plugins['title'] = 'Writing Plugins'
-to_write.append(
-    ('Plugins',
-     'Writing Plugins',
-     os.path.join(doc, 'writing_plugins.html'), tpl, writing_plugins))
-
-
-# error class plugins
-ecp = {'body': to_html(errorclass.__doc__)}
-ecp.update(std_info)
-ecp['title'] = 'ErrorClass Plugins'
-to_write.append(
-    ('Plugins',
-     'ErrorClass Plugins',
-     os.path.join(doc, 'errorclassplugin.html'), tpl, ecp))
-
-# interface
-itf = {'body': to_html(textwrap.dedent(IPluginInterface.__doc__))}
-
-# methods
-attr = [(a, getattr(IPluginInterface, a)) for a in dir(IPluginInterface)]
-methods = [m for m in attr if inspect.ismethod(m[1])]
-methods.sort()
-# print "Documenting methods", [a[0] for a in methods]
-
-method_html = []
-method_tpl = """
-<div class="method %(extra_class)s">
-<a name="%(name)s">
-<span class="name">%(name)s</span><span class="arg">%(arg)s</span></a>
-<div class="doc">%(body)s</div>
-</div>
-"""
-
-menu_links = {}
-
-m_attrs = ('_new', 'changed', 'deprecated', 'generative', 'chainable')
-for m in methods:
-    name, meth = m
-    ec = []
-    for att in m_attrs:
-        if hasattr(meth, att):
-            ec.append(att.replace('_', ''))
-            menu_links.setdefault(att.replace('_', ''), []).append(name)
-    # padding evens the lines
-    print name
-    mdoc = {'body': to_html(textwrap.dedent('        ' + meth.__doc__))}
-    argspec = formatargspec(meth)
-    mdoc.update({'name': name,
-                 'extra_class': ' '.join(ec),
-                 'arg': argspec})
-    method_html.append(method_tpl % mdoc)
-
-itf['methods'] = ''.join(method_html)
-itf.update(std_info)
-itf['title'] = 'Plugin Interface'
-
-menu = []
-for section in ('new', 'changed', 'deprecated'):
-    menu.append('<h2>%s methods</h2>' % section.title())
-    menu.append('<ul><li>')
-    menu.append('</li><li>'.join([
-        '<a href="#%(name)s">%(name)s</a>' % {'name': n}
-        for n in menu_links[section]]))
-    menu.append('</li></ul>')
-itf['sub_menu'] = ''.join(menu)
-
-to_write.append(
-    ('Plugins',
-     'Plugin Interface',
-     os.path.join(doc, 'plugin_interface.html'), api_tpl, itf))
-
-
-# individual plugin usage docs
-from nose.plugins.builtin import builtins
-
-pmeths = [m[0] for m in methods[:]
-          if not 'options' in m[0].lower()]
-pmeths.append('options')
-pmeths.sort()
-
-for modulename, clsname in builtins:
-    _, _, modname = modulename.split('.')
-    mod = resolve_name(modulename)
-    cls = getattr(mod, clsname)
-    filename = os.path.join(doc, 'plugin_%s.html' % modname)
-    print modname, filename
-    if not mod.__doc__:
-        print "No docs"
-        continue
-    pdoc = {'body': to_html(mod.__doc__)}
-    pdoc.update(std_info)
-    pdoc['title'] = 'builtin plugin: %s' % modname
-
-    # options
-    parser = OptionParser(add_help_option=False)
-    plug = cls()
-    plug.addOptions(parser)
-    options = parser.format_option_help()
-    pdoc['options'] = options
-
-    # hooks used
-    hooks = []
-    for m in pmeths:
-        if getattr(cls, m, None):
-            hooks.append('<li><a href="plugin_interface.html#%(name)s">'
-                         '%(name)s</a></li>' % {'name': m})
-    pdoc['hooks'] = ''.join(hooks)
-
-    source = inspect.getsource(mod)
-    pdoc['source'] = highlight(source, PythonLexer(), HtmlFormatter())
+def main():
+    root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
+    doc = os.path.join(root, 'doc')
+    tpl = open(os.path.join(doc, 'doc.html.tpl'), 'r').read()
+    api_tpl = open(os.path.join(doc, 'plugin_api.html.tpl'), 'r').read()
+    plug_tpl = open(os.path.join(doc, 'plugin.html.tpl'), 'r').read()
+    std_info = {
+        'version': nose.__version__,
+        'date': time.ctime()
+        }
+    to_write = []
+
+
+    # plugins
+    from nose import plugins
+    from nose.plugins.base import IPluginInterface
+    from nose.plugins import errorclass
+
+    # writing plugins guide
+    writing_plugins = {'body': to_html(plugins.__doc__)}
+    writing_plugins.update(std_info)
+    writing_plugins['title'] = 'Writing Plugins'
     to_write.append(
         ('Plugins',
-         'Builtin Plugin: %s' % modname,
-         os.path.join(doc, filename), plug_tpl, pdoc))
-
-
-# individual module docs
-b = Browser(['nose','nose.plugins.manager', 'nose.plugins.plugintest'],
-            exclude_modules=['nose.plugins', 'nose.ext'])
-for mod in b.modules(recursive=1):
-    if mod.name == 'nose':
-        # no need to regenerate, this is the source of the doc index page
-        continue
-    print mod.qualified_name()
-    document_module(mod)
-
-
-# plugin examples doctests
-for testfile in plugin_example_tests():
-    document_rst_test(testfile, "Plugin Examples")
-
-
-# finally build the menu and write all pages
-menu = []
-sections = odict()
-for page in to_write:
-    section, _, _, _, _ = page
-    sections.setdefault(section, []).append(page)
-
-for section, pages in sections.items():
-    menu.append('<h2>%s</h2>' % section)
-    menu.append('<ul>')
-    pages.sort()
-    menu.extend([
-        '<li><a href="%s">%s</a></li>' % (os.path.basename(filename), title)
-        for _, title, filename, _, _ in pages ])
-    menu.append('</ul>')
-
-menu = ''.join(menu)
-for section, title, filename, template, ctx in to_write:
-    ctx['menu'] = menu
-    write(filename, template, ctx)
-
-# doc section index page
-idx_tpl = open(os.path.join(doc, 'index.html.tpl'), 'r').read()
-idx = {
-    'title': 'API documentation',
-    'menu': menu}
-idx.update(std_info)
-write(os.path.join(doc, 'index.html'), idx_tpl, idx)
+         'Writing Plugins',
+         os.path.join(doc, 'writing_plugins.html'), tpl, writing_plugins))
+
 
+    # error class plugins
+    ecp = {'body': to_html(errorclass.__doc__)}
+    ecp.update(std_info)
+    ecp['title'] = 'ErrorClass Plugins'
+    to_write.append(
+        ('Plugins',
+         'ErrorClass Plugins',
+         os.path.join(doc, 'errorclassplugin.html'), tpl, ecp))
+
+    # interface
+    itf = {'body': to_html(textwrap.dedent(IPluginInterface.__doc__))}
+
+    # methods
+    attr = [(a, getattr(IPluginInterface, a)) for a in dir(IPluginInterface)]
+    methods = [m for m in attr if inspect.ismethod(m[1])]
+    methods.sort()
+    # print "Documenting methods", [a[0] for a in methods]
+
+    method_html = []
+    method_tpl = """
+    <div class="method %(extra_class)s">
+    <a name="%(name)s">
+    <span class="name">%(name)s</span><span class="arg">%(arg)s</span></a>
+    <div class="doc">%(body)s</div>
+    </div>
+    """
+
+    menu_links = {}
+
+    m_attrs = ('_new', 'changed', 'deprecated', 'generative', 'chainable')
+    for m in methods:
+        name, meth = m
+        ec = []
+        for att in m_attrs:
+            if hasattr(meth, att):
+                ec.append(att.replace('_', ''))
+                menu_links.setdefault(att.replace('_', ''), []).append(name)
+        # padding evens the lines
+        print name
+        mdoc = {'body': to_html(textwrap.dedent('        ' + meth.__doc__))}
+        argspec = formatargspec(meth)
+        mdoc.update({'name': name,
+                     'extra_class': ' '.join(ec),
+                     'arg': argspec})
+        method_html.append(method_tpl % mdoc)
+
+    itf['methods'] = ''.join(method_html)
+    itf.update(std_info)
+    itf['title'] = 'Plugin Interface'
+
+    menu = []
+    for section in ('new', 'changed', 'deprecated'):
+        menu.append('<h2>%s methods</h2>' % section.title())
+        menu.append('<ul><li>')
+        menu.append('</li><li>'.join([
+            '<a href="#%(name)s">%(name)s</a>' % {'name': n}
+            for n in menu_links[section]]))
+        menu.append('</li></ul>')
+    itf['sub_menu'] = ''.join(menu)
+
+    to_write.append(
+        ('Plugins',
+         'Plugin Interface',
+         os.path.join(doc, 'plugin_interface.html'), api_tpl, itf))
+
+
+    # individual plugin usage docs
+    from nose.plugins.builtin import builtins
+
+    pmeths = [m[0] for m in methods[:]
+              if not 'options' in m[0].lower()]
+    pmeths.append('options')
+    pmeths.sort()
+
+    for modulename, clsname in builtins:
+        _, _, modname = modulename.split('.')
+        mod = resolve_name(modulename)
+        cls = getattr(mod, clsname)
+        filename = os.path.join(doc, 'plugin_%s.html' % modname)
+        print modname, filename
+        if not mod.__doc__:
+            print "No docs"
+            continue
+        pdoc = {'body': to_html(mod.__doc__)}
+        pdoc.update(std_info)
+        pdoc['title'] = 'builtin plugin: %s' % modname
+
+        # options
+        parser = OptionParser(add_help_option=False)
+        plug = cls()
+        plug.addOptions(parser)
+        options = parser.format_option_help()
+        pdoc['options'] = options
+
+        # hooks used
+        hooks = []
+        for m in pmeths:
+            if getattr(cls, m, None):
+                hooks.append('<li><a href="plugin_interface.html#%(name)s">'
+                             '%(name)s</a></li>' % {'name': m})
+        pdoc['hooks'] = ''.join(hooks)
+
+        source = inspect.getsource(mod)
+        pdoc['source'] = highlight(source, PythonLexer(), HtmlFormatter())
+        to_write.append(
+            ('Plugins',
+             'Builtin Plugin: %s' % modname,
+             os.path.join(doc, filename), plug_tpl, pdoc))
+
+
+    # individual module docs
+    b = Browser(['nose','nose.plugins.manager', 'nose.plugins.plugintest'],
+                exclude_modules=['nose.plugins', 'nose.ext'])
+    for mod in b.modules(recursive=1):
+        if mod.name == 'nose':
+            # no need to regenerate, this is the source of the doc index page
+            continue
+        print mod.qualified_name()
+        document_module(mod)
+
+
+    # plugin examples doctests
+    for testfile in plugin_example_tests():
+        document_rst_test(testfile, "Plugin Examples")
+
+
+    # finally build the menu and write all pages
+    menu = []
+    sections = odict()
+    for page in to_write:
+        section, _, _, _, _ = page
+        sections.setdefault(section, []).append(page)
+
+    for section, pages in sections.items():
+        menu.append('<h2>%s</h2>' % section)
+        menu.append('<ul>')
+        pages.sort()
+        menu.extend([
+            '<li><a href="%s">%s</a></li>' % (os.path.basename(filename), title)
+            for _, title, filename, _, _ in pages ])
+        menu.append('</ul>')
+
+    menu = ''.join(menu)
+    for section, title, filename, template, ctx in to_write:
+        ctx['menu'] = menu
+        write(filename, template, ctx)
+
+    # doc section index page
+    idx_tpl = open(os.path.join(doc, 'index.html.tpl'), 'r').read()
+    idx = {
+        'title': 'API documentation',
+        'menu': menu}
+    idx.update(std_info)
+    write(os.path.join(doc, 'index.html'), idx_tpl, idx)
+
+if __name__ == '__main__':
+    main()
diff --git a/scripts/mkwiki.py b/scripts/mkwiki.py
index 4a0a354..ad0c956 100755
--- a/scripts/mkwiki.py
+++ b/scripts/mkwiki.py
@@ -15,6 +15,8 @@ import sys
 import textwrap
 import time
 
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
+from mkdocs import formatargspec
 
 # constants
 success = 0
@@ -208,7 +210,7 @@ def plugin_interface():
     mdoc = []
     for m in methods:
         # FIXME fix the arg list so literal os.environ is not in there
-        mdoc.append('*%s%s*\n\n' %  (m.name, m.formatargs()))
+        mdoc.append('*%s%s*\n\n' %  (m.name, formatargspec(m.obj)))
         # FIXME this is resulting in poorly formatted doc sections
         mdoc.append(' ' + m.doc().replace('\n', '\n '))
         mdoc.append('\n\n')
@@ -344,10 +346,20 @@ class Wiki(object):
         if page in self.newpages:
             runcmd('svn add %s' % self.filename(page))
 
-        
+            
+def findwiki(root):
+    if not root:
+        raise ValueError("wiki path not found")
+    if not os.path.isdir(root):
+        return findwiki(os.path.dirname(root))
+    entries = os.listdir(root)
+    if 'wiki' in entries:
+        return os.path.join(root, 'wiki')
+    return findwiki(os.path.dirname(root))
+
+
 def main():
-    path = os.path.abspath(
-        os.path.join(os.path.dirname(__file__), '..', '..', '..', 'wiki'))
+    path = findwiki(os.path.abspath(__file__))
     mkwiki(path)