zr-v4/Tools/autotest/param_metadata/rstemit.py

#!/usr/bin/env python

import re
from param import *
from emit import Emit
import cgi

# Emit docs in a RST format
class RSTEmit(Emit):

    def blurb(self):
        return '''This is a complete list of the parameters which can be set (e.g. via the MAVLink protocol) to control vehicle behaviour. They are stored in persistent storage on the vehicle.

This list is automatically generated from the latest ardupilot source code, and so may contain parameters which are not yet in the stable released versions of the code.
'''
    def toolname(self):
        return "Tools/autotest/param_metadata/param_parse.py"

    def __init__(self):
        output_fname = 'Parameters.rst'
        self.f = open(output_fname, mode='w')
        self.spacer = re.compile("^", re.MULTILINE)
        self.rstescape = re.compile("([^a-zA-Z0-9\n 	])")
        self.preamble = '''.. Dynamically generated list of documented parameters
.. This page was generated using {toolname}

.. DO NOT EDIT


.. _parameters:

Complete Parameter List
=======================

{blurb}

'''.format(blurb=self.escape(self.blurb()),
           toolname=self.escape(self.toolname()))
        self.t = ''

    def escape(self, s):
        ret = re.sub(self.rstescape, "\\\\\g<1>", s)
        return ret

    def close(self):
        self.f.write(self.preamble)
        self.f.write(self.t)
        self.f.close()


    def start_libraries(self):
        pass

    def tablify_row(self, row, widths):
        ret = ""
        i=0
        for item in row:
            ret += "| " + item + " "*(widths[i]-len(item)-1)
            i += 1
        ret += "|"
        return ret

    def tablify(self, rows, headings=None):
        if headings is None:
            print("headings must be supplied ATM")
            sys.exit(1)

        # determine column widths
        widths = [0] * len(headings)
        i=0
        for heading in headings:
            widths[i] = len(str(heading)) + 2 # +2 for leading/trailing ws
            i += 1
        for row in rows:
            i=0
            for value in row:
                width = len(str(value)) + 2 # +2 for leading/trailing ws
                if width > widths[i]:
                    widths[i] = width
                i += 1
        # create dividing lines
        bar = ""
        heading_bar = ""
        for width in widths:
            bar += "+"
            heading_bar += "+"
            bar += "-" * width
            heading_bar += "=" * width
        bar += "+"
        heading_bar += "+"

        # create table
        ret = bar + "\n"
        ret += self.tablify_row(headings, widths) + "\n"
        ret += heading_bar + "\n"
        for row in rows:
            ret += self.tablify_row(row, widths) + "\n"
            ret += bar + "\n"

        return ret

    def emit(self, g, f):
        tag = '%s Parameters' % self.escape(g.name)
        reference = "parameters_" + g.name
        ret = '''

.. _{reference}:

{tag}
{underline}
'''.format(tag=tag,underline="-" * len(tag),
           reference=reference)

        for param in g.params:
            if not hasattr(param, 'DisplayName') or not hasattr(param, 'Description'):
                continue
            d = param.__dict__
            if self.annotate_with_vehicle:
                name = param.name
            else:
                name = param.name.split(':')[-1]
            tag = '%s: %s' % (self.escape(name), self.escape(param.DisplayName), )
            tag = tag.strip()
            reference = param.name
            # remove e.g. "ArduPlane:" from start of parameter name:
            if self.annotate_with_vehicle:
                reference = g.name + "_" + reference.split(":")[-1]
            else:
                reference = reference.split(":")[-1]

            ret += '''

.. _{reference}:

{tag}
{tag_underline}
'''.format(tag=tag, tag_underline='~'*len(tag), reference=reference)

            if d.get('User',None) == 'Advanced':
                ret += '\n| *Note: This parameter is for advanced users*'
            ret += "\n\n%s\n" % self.escape(param.Description)

            headings = []
            rows = []
            for field in param.__dict__.keys():
                if field not in ['name', 'DisplayName', 'Description', 'User'] and field in known_param_fields:
                    if field == 'Values' and Emit.prog_values_field.match(param.__dict__[field]):
                        values = (param.__dict__[field]).split(',')
                        rows = []
                        for value in values:
                            v = [ x.strip() for x in value.split(':') ]
                            rows.append(v)
                        ret += "\n" + self.tablify(rows, headings=['Value','Meaning']) + "\n\n"
                    else:
                        ret += "%s: %s\n" % (field, cgi.escape(param.__dict__[field]))

        self.t += ret