Poodletooth-iLand/tools/write_rpc_doc.py

#!/usr/bin/env python2
import collections
import compiler
import re


class CategoryParser:
    def __init__(self, filepath):
        self.filepath = filepath

        self.categories = {}

    def parse(self):
        with open(self.filepath, 'r') as f:
            for i, line in enumerate(f.readlines()):
                line = line.strip()
                if (not line.startswith('# --- ')) or (not line.endswith(' ---')):
                    continue
                self.addCategory(i + 1, line[6:-4].title())

    def addCategory(self, lineno, category):
        self.categories[lineno] = category

    def getCategory(self, lineno):
        category = 'Unknown'
        for k in sorted(self.categories.keys()):
            if k > lineno:
                break
            category = self.categories[k]
        return category


class MethodParser(CategoryParser):
    def __init__(self, filepath):
        CategoryParser.__init__(self, filepath)

        # Order matters, so store the method information in an OrderedDict:
        self.methods = collections.OrderedDict()

    def parse(self):
        CategoryParser.parse(self)

        # Get the root node:
        node = compiler.parseFile(self.filepath).node

        # Parse any class objects:
        for child in node.getChildren():
            if isinstance(child, compiler.ast.Class):
                self.parseClass(child)

    def parseClass(self, node):
        # Skip past the class definition, and go into the body:
        stmt = node.getChildNodes()[-1]

        # Parse any function objects:
        for child in stmt.getChildren():
            if isinstance(child, compiler.ast.Function):
                self.parseFunction(child)

    def parseFunction(self, node):
        # First, verify that this is an RPC method:
        if not node.name.startswith('rpc_'):
            # RPC methods are required to have their name begin with 'rpc_'.
            return
        name = node.name[4:]
        if node.decorators is None:
            # RPC methods are also required to utilize the @rpcmethod
            # decorator.
            return
        for decorator in node.decorators:
            if decorator.node.name != 'rpcmethod':
                continue
            accessLevel = 'Unknown'
            for arg in decorator.args:
                if arg.name != 'accessLevel':
                    continue

                # Format the access level string:
                accessLevel = ' '.join(arg.expr.name.split('_')).title()
            break
        else:
            return

        # A docstring is also required:
        if node.doc is None:
            return

        # Get rid of the indentation in our docstring so that we can have an
        # easier time parsing it:
        lines = node.doc.split('\n')
        for i, line in enumerate(lines):
            lines[i] = line.lstrip()
        doc = '\n'.join(lines)

        # Get the category in which this method is underneath:
        category = self.getCategory(node.lineno)

        # Store this method's information:
        self.methods.setdefault(category, []).append((name, accessLevel, doc))

    def getMethods(self):
        return self.methods


class MediaWikiGenerator:
    def __init__(self, methods):
        self.methods = methods

        self.content = ''

    def generate(self):
        # Start on a clean slate:
        self.content = ''

        # Write the documentation header:
        self.writeHeader()

        # Write the categories and methods:
        for category, methods in self.methods.items():
            self.writeCategory(category)
            for name, accessLevel, doc in methods:
                self.writeMethod(name, accessLevel, doc)

        # Write the documentation footer:
        self.writeFooter()

        return self.content

    def writeHeader(self):
        # Force a table of contents:
        self.content += '__TOC__\n'

    def writeCategory(self, category):
        self.content += '= %s =\n' % category

    def writeMethod(self, name, accessLevel, doc):
        # First, add the method name and access level:
        self.writeHeading(3, name + ' <sub>- <code>%s</code></sub>' % accessLevel)

        # Split the docstring by the '\n\n' terminator:
        doc = doc.split('\n\n')

        # A summary is required, so let's assume it's first:
        summary = doc[0][9:].strip()
        self.writeBlockQuote(' '.join(summary.split('\n')))

        # Let's do parameters next if we have them:
        for entry in doc:
            if entry.startswith('Parameters:'):
                entry = entry[13:].strip()
                break
        else:
            entry = None
        if entry is not None:
            parameters = []
            for parameter in re.split('\\n\\[|\\n<', entry):
                name, description = parameter.split(' = ', 1)
                type, name = name.strip()[:-1].split(' ', 1)
                description = ' '.join(description.split('\n'))
                parameters.append((name, type, description))
            self.writeParameters(parameters)

        # Finally, we have an optional example response:
        for entry in doc:
            if entry.startswith('Example response:'):
                entry = entry[18:].strip()
                break
        else:
            entry = None
        if entry is not None:
            self.content += '{|\n'
            self.content += '|-\n'
            if (not entry.startswith('On success:')) or (
                'On failure:' not in entry):
                # Generate a single-row table:
                self.content += '! Example Response\n'
                self.content += '| <nowiki>%s</nowiki>\n' % entry
            else:
                # Generate a double-row table:
                success, failure = entry[12:].split('On failure:', 1)
                self.content += '! rowspan="2"|Example Response\n'
                self.content += '| Success\n'
                self.content += '| <nowiki>%s</nowiki>\n' % success.strip()
                self.content += '|-\n'
                self.content += '| Failure\n'
                self.content += '| <nowiki>%s</nowiki>\n' % failure.strip()
            self.content += '|}\n'

        return self.content

    def writeHeading(self, size, text):
        self.content += '<h%d>%s</h%d>\n' % (size, text, size)

    def writeBlockQuote(self, text):
        self.content += '<blockquote><nowiki>%s</nowiki></blockquote>\n' % text

    def writeParameters(self, parameters):
        self.content += '{|\n'
        self.content += '|-\n'
        self.content += '! rowspan="%d"|Parameters\n' % (len(parameters) + 1)
        self.content += '! Name\n'
        self.content += '! Type\n'
        self.content += '! Description\n'
        for name, type, description in parameters:
            self.content += '|-\n'
            self.content += '| <nowiki>%s</nowiki>\n' % name
            self.content += '| <nowiki>%s</nowiki>\n' % type
            self.content += '| <nowiki>%s</nowiki>\n' % description
        self.content += '|}\n'

    def writeFooter(self):
        # Let the reader know that this documentation was automatically
        # generated:
        self.content += '----\n'
        self.content += ("''This document was automatically generated by the "
                         "<code>write_rpc_doc.py</code> utility.''\n")


parser = MethodParser('toontown/rpc/ToontownRPCHandler.py')
parser.parse()
generator = MediaWikiGenerator(parser.getMethods())
with open('wiki.txt', 'w') as f:
    f.write(generator.generate())