From 720c725a931d8ea840bebc3e8e547f1bd2a7b41f Mon Sep 17 00:00:00 2001 From: James Vega Date: Fri, 14 Nov 2003 18:53:46 +0000 Subject: [PATCH] Documentation pages now link to each other. There is also an index sorted by plugin (index.html) and an index sorted by command (commands.html) --- tools/generate-plugin-documentation.py | 242 +++++++++++++++++-------- 1 file changed, 169 insertions(+), 73 deletions(-) diff --git a/tools/generate-plugin-documentation.py b/tools/generate-plugin-documentation.py index 7cf9b4446..4a5461b6c 100755 --- a/tools/generate-plugin-documentation.py +++ b/tools/generate-plugin-documentation.py @@ -47,87 +47,183 @@ conf.logDir = 'test-log' import debug import callbacks +commandDict = {} -def makePluginDocumentation(filename): - print 'Generating documentation for %s' % filename - trClasses = { 'treven':'trodd', 'trodd':'treven' } - trClass = 'treven' - pluginName = filename.split('.')[0] - moduleInfo = imp.find_module(pluginName, conf.pluginDirs) - module = imp.load_module(pluginName, *moduleInfo) +def prepIndex(): directory = os.path.join('docs', 'plugins') if not os.path.exists(directory): os.mkdir(directory) - if not hasattr(module, 'Class'): - print '%s is not a plugin.' % filename - return - try: - plugin = module.Class() - except Exception, e: - print '%s could not be loaded: %s' % (filename, debug.exnToString(e)) - return - if isinstance(plugin, callbacks.Privmsg) and not \ - isinstance(plugin, callbacks.PrivmsgRegexp): - fd = file(os.path.join(directory,'%s.html' % pluginName), 'w') - fd.write(textwrap.dedent(""" - - - - - Documentation for the %s plugin for Supybot - -
-

%s



- - """) % (pluginName, cgi.escape(module.__doc__ or ""))) - for attr in dir(plugin): - if plugin.isCommand(attr): - method = getattr(plugin, attr) - if hasattr(method, '__doc__'): - doclines = method.__doc__.splitlines() - help = doclines.pop(0) - morehelp = 'This command has no detailed help.' - if doclines: - doclines = filter(None, doclines) - doclines = map(str.strip, doclines) - morehelp = ' '.join(doclines) - help = cgi.escape(help) - morehelp = cgi.escape(morehelp) - trClass = trClasses[trClass] - fd.write(textwrap.dedent(""" - - """) % (trClass, attr, help, morehelp)) - fd.write(textwrap.dedent(""" -
CommandArgs - Detailed Help
%s%s%s -
- """)) - if hasattr(module, 'example'): - s = module.example.encode('string-escape') - s = s.replace('\\n', '\n') - s = s.replace("\\'", "'") - fd.write(textwrap.dedent(""" -

Here's an example session with this plugin:

- 
-            %s
-
- """) % cgi.escape(s)) - fd.write(textwrap.dedent(""" -
- - - """)) - fd.close() + fd = file(os.path.join(directory, 'index.html'), 'w') + fd.write(textwrap.dedent(""" + + + + + Supybot plugin documentation + +
+

Supybot Plugin Documentation Index

+ Plugin (Command list)

+ """)) + fd.close() -if __name__ == '__main__': +def makePluginDocumentation(pluginWindow): + global commandDict + trClasses = { 'treven':'trodd', 'trodd':'treven' } + trClass = 'treven' + (pluginName, module, plugin) = pluginWindow[1] + print 'Generating documentation for %s.py' % pluginName + prev = pluginWindow[0][0] or 'index' + next = pluginWindow[2][0] or 'index' + directory = os.path.join('docs', 'plugins') + if not os.path.exists(directory): + os.mkdir(directory) + id = file(os.path.join(directory, 'index.html'), 'a') + id.write(textwrap.dedent(""" + %s + """ % (pluginName, pluginName.capitalize()))) + fd = file(os.path.join(directory,'%s.html' % pluginName), 'w') + fd.write(textwrap.dedent(""" + + + + + Documentation for the %s plugin for Supybot + + + + +
+

%s



+ + """) % (pluginName, next, prev, cgi.escape(module.__doc__ or ""))) + attrs = [x for x in dir(plugin) if plugin.isCommand(x) and not + x.startswith('_')] + id.write('(%s)
\n' % ', '.join(attrs)) + for attr in attrs: + if attr in commandDict: + commandDict[attr].append(pluginName) + else: + commandDict[attr] = [pluginName] + method = getattr(plugin, attr) + if hasattr(method, '__doc__'): + doclines = method.__doc__.splitlines() + help = doclines.pop(0) + morehelp = 'This command has no detailed help.' + if doclines: + doclines = filter(None, doclines) + doclines = map(str.strip, doclines) + morehelp = ' '.join(doclines) + help = cgi.escape(help) + morehelp = cgi.escape(morehelp) + trClass = trClasses[trClass] + fd.write(textwrap.dedent(""" + + """) % (trClass, attr, help, morehelp)) + fd.write(textwrap.dedent(""" +
CommandArgs + Detailed Help
%s%s%s +
+ """)) + if hasattr(module, 'example'): + s = module.example.encode('string-escape') + s = s.replace('\\n', '\n') + s = s.replace("\\'", "'") + fd.write(textwrap.dedent(""" +

Here's an example session with this plugin:

+ 
+        %s
+
+ """) % cgi.escape(s)) + fd.write(textwrap.dedent(""" +
+
+
+ <- %s | Index | %s -> +
+ + + """ % (prev, prev.capitalize(), next, next.capitalize()))) + fd.close() + id.close() + +def finishIndex(): + directory = os.path.join('docs', 'plugins') + if not os.path.exists(directory): + os.mkdir(directory) + fd = file(os.path.join(directory, 'index.html'), 'a') + fd.write(textwrap.dedent(""" +
+ + + """)) + fd.close() + +def makeCommandsIndex(): + global commandDict + directory = os.path.join('docs', 'plugins') + if not os.path.exists(directory): + os.mkdir(directory) + fd = file(os.path.join(directory, 'commands.html'), 'w') + fd.write(textwrap.dedent(""" + + + + + Supybot Commands Index + +
+

Supybot Commands Index

+ Command (Plugins)

+ """)) + commands = [c for c in commandDict.iterkeys()] + commands.sort() + for command in commands: + plugins = commandDict[command] + plugins.sort() + fd.write('%s (%s)
\n' % (command, + ', '.join(['%s' % (p, p) + for p in plugins]))) + fd.write(textwrap.dedent(""" +
+ + + """)) + fd.close() + +def genPlugins(): for directory in conf.pluginDirs: for filename in os.listdir(directory): if filename.endswith('.py') and filename[0].isupper(): - makePluginDocumentation(filename) + pluginName = filename.split('.')[0] + moduleInfo = imp.find_module(pluginName, conf.pluginDirs) + module = imp.load_module(pluginName, *moduleInfo) + if not hasattr(module, 'Class'): + print '%s is not a plugin.' % filename + continue + try: + plugin = module.Class() + except Exception, e: + print '%s could not be loaded: %s' % (filename, + debug.exnToString(e)) + continue + if isinstance(plugin, callbacks.Privmsg) and not \ + isinstance(plugin, callbacks.PrivmsgRegexp): + yield (pluginName, module, plugin) + +if __name__ == '__main__': + prepIndex() + plugins = [p for p in genPlugins()] + plugins.sort() + plugins = [(None,)] + plugins + [(None,)] + for pluginWindow in window(plugins, 3): + makePluginDocumentation(pluginWindow) + finishIndex() + makeCommandsIndex() - - - # vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78: