forked from Archive/PX4-Autopilot
Merge pull request #766 from PX4/param_tool
Improvements to parameter documentation script
This commit is contained in:
commit
afa6d170ca
|
@ -0,0 +1,2 @@
|
|||
parameters.wiki
|
||||
parameters.xml
|
|
@ -1,4 +0,0 @@
|
|||
parameters.wiki
|
||||
parameters.xml
|
||||
parameters.wikirpc.xml
|
||||
cookies.txt
|
|
@ -1,9 +1 @@
|
|||
h1. PX4 Parameters Processor
|
||||
|
||||
It's designed to scan PX4 source codes, find declarations of tunable parameters,
|
||||
and generate the list in various formats.
|
||||
|
||||
Currently supported formats are:
|
||||
|
||||
* XML for the parametric UI generator
|
||||
* Human-readable description in DokuWiki format
|
||||
This folder contains a python library used by px_process_params.py
|
||||
|
|
|
@ -0,0 +1 @@
|
|||
__all__ = ["srcscanner", "srcparser", "xmlout", "dokuwikiout", "dokuwikirpc"]
|
|
@ -0,0 +1,44 @@
|
|||
from xml.sax.saxutils import escape
|
||||
import codecs
|
||||
|
||||
class DokuWikiTablesOutput():
|
||||
def __init__(self, groups):
|
||||
result = ("====== Parameter Reference ======\n"
|
||||
"<note>**This list is auto-generated from the source code** and contains the most recent parameter documentation.</note>\n"
|
||||
"\n")
|
||||
for group in groups:
|
||||
result += "==== %s ====\n\n" % group.GetName()
|
||||
result += "|< 100% 25% 45% 10% 10% 10% >|\n"
|
||||
result += "^ Name ^ Description ^ Min ^ Max ^ Default ^\n"
|
||||
result += "^ ::: ^ Comment ^^^^\n"
|
||||
for param in group.GetParams():
|
||||
code = param.GetFieldValue("code")
|
||||
name = param.GetFieldValue("short_desc")
|
||||
min_val = param.GetFieldValue("min")
|
||||
max_val = param.GetFieldValue("max")
|
||||
def_val = param.GetFieldValue("default")
|
||||
long_desc = param.GetFieldValue("long_desc")
|
||||
|
||||
if name == code:
|
||||
name = ""
|
||||
else:
|
||||
name = name.replace("\n", " ")
|
||||
name = name.replace("|", "%%|%%")
|
||||
name = name.replace("^", "%%^%%")
|
||||
|
||||
result += "| **%s** |" % code
|
||||
result += " %s |" % name
|
||||
result += " %s |" % (min_val or "")
|
||||
result += " %s |" % (max_val or "")
|
||||
result += " %s |" % (def_val or "")
|
||||
result += "\n"
|
||||
|
||||
if long_desc is not None:
|
||||
result += "| ::: | <div>%s</div> ||||\n" % long_desc
|
||||
|
||||
result += "\n"
|
||||
self.output = result;
|
||||
|
||||
def Save(self, filename):
|
||||
with codecs.open(filename, 'w', 'utf-8') as f:
|
||||
f.write(self.output)
|
|
@ -0,0 +1,16 @@
|
|||
try:
|
||||
import xmlrpclib
|
||||
except ImportError:
|
||||
import xmlrpc.client as xmlrpclib
|
||||
|
||||
# See https://www.dokuwiki.org/devel:xmlrpc for a list of available functions!
|
||||
# Usage example:
|
||||
# xmlrpc = dokuwikirpc.get_xmlrpc(url, username, password)
|
||||
# print(xmlrpc.dokuwiki.getVersion())
|
||||
|
||||
def get_xmlrpc(url, username, password):
|
||||
#proto, url = url.split("://")
|
||||
#url = proto + "://" + username + ":" + password + "@" + url + "/lib/exe/xmlrpc.php"
|
||||
url += "/lib/exe/xmlrpc.php?u=" + username + "&p=" + password
|
||||
|
||||
return xmlrpclib.ServerProxy(url)
|
|
@ -1,31 +0,0 @@
|
|||
import codecs
|
||||
|
||||
class DokuWikiListingsOutput():
|
||||
def __init__(self, groups):
|
||||
result = ""
|
||||
for group in groups:
|
||||
result += "==== %s ====\n\n" % group.GetName()
|
||||
for param in group.GetParams():
|
||||
code = param.GetFieldValue("code")
|
||||
name = param.GetFieldValue("short_desc")
|
||||
if code != name:
|
||||
name = "%s (%s)" % (name, code)
|
||||
result += "=== %s ===\n\n" % name
|
||||
long_desc = param.GetFieldValue("long_desc")
|
||||
if long_desc is not None:
|
||||
result += "%s\n\n" % long_desc
|
||||
min_val = param.GetFieldValue("min")
|
||||
if min_val is not None:
|
||||
result += "* Minimal value: %s\n" % min_val
|
||||
max_val = param.GetFieldValue("max")
|
||||
if max_val is not None:
|
||||
result += "* Maximal value: %s\n" % max_val
|
||||
def_val = param.GetFieldValue("default")
|
||||
if def_val is not None:
|
||||
result += "* Default value: %s\n" % def_val
|
||||
result += "\n"
|
||||
self.output = result
|
||||
|
||||
def Save(self, filename):
|
||||
with codecs.open(filename, 'w', 'utf-8') as f:
|
||||
f.write(self.output)
|
|
@ -1,76 +0,0 @@
|
|||
from xml.sax.saxutils import escape
|
||||
import codecs
|
||||
|
||||
class DokuWikiTablesOutput():
|
||||
def __init__(self, groups):
|
||||
result = "====== Parameter Reference ======\nThis list is auto-generated every few minutes and contains the most recent parameter names and default values.\n\n"
|
||||
for group in groups:
|
||||
result += "==== %s ====\n\n" % group.GetName()
|
||||
result += "|< 100% 20% 20% 10% 10% 10% 30%>|\n"
|
||||
result += "^ Name ^ Description ^ Min ^ Max ^ Default ^ Comment ^\n"
|
||||
for param in group.GetParams():
|
||||
code = param.GetFieldValue("code")
|
||||
name = param.GetFieldValue("short_desc")
|
||||
min_val = param.GetFieldValue("min")
|
||||
max_val = param.GetFieldValue("max")
|
||||
def_val = param.GetFieldValue("default")
|
||||
long_desc = param.GetFieldValue("long_desc")
|
||||
|
||||
name = name.replace("\n", " ")
|
||||
result += "| %s | %s |" % (code, name)
|
||||
|
||||
if min_val is not None:
|
||||
result += " %s |" % min_val
|
||||
else:
|
||||
result += " |"
|
||||
|
||||
if max_val is not None:
|
||||
result += " %s |" % max_val
|
||||
else:
|
||||
result += " |"
|
||||
|
||||
if def_val is not None:
|
||||
result += " %s |" % def_val
|
||||
else:
|
||||
result += " |"
|
||||
|
||||
if long_desc is not None:
|
||||
long_desc = long_desc.replace("\n", " ")
|
||||
result += " %s |" % long_desc
|
||||
else:
|
||||
result += " |"
|
||||
|
||||
result += "\n"
|
||||
result += "\n"
|
||||
self.output = result;
|
||||
|
||||
def Save(self, filename):
|
||||
with codecs.open(filename, 'w', 'utf-8') as f:
|
||||
f.write(self.output)
|
||||
|
||||
def SaveRpc(self, filename):
|
||||
with codecs.open(filename, 'w', 'utf-8') as f:
|
||||
f.write("""<?xml version='1.0'?>
|
||||
<methodCall>
|
||||
<methodName>wiki.putPage</methodName>
|
||||
<params>
|
||||
<param>
|
||||
<value>
|
||||
<string>:firmware:parameters</string>
|
||||
</value>
|
||||
</param>
|
||||
<param>
|
||||
<value>
|
||||
<string>""")
|
||||
f.write(escape(self.output))
|
||||
f.write("""</string>
|
||||
</value>
|
||||
</param>
|
||||
<param>
|
||||
<value>
|
||||
<name>sum</name>
|
||||
<string>Updated parameters automagically from code.</string>
|
||||
</value>
|
||||
</param>
|
||||
</params>
|
||||
</methodCall>""")
|
|
@ -1,67 +0,0 @@
|
|||
#!/usr/bin/env python
|
||||
############################################################################
|
||||
#
|
||||
# Copyright (C) 2013 PX4 Development Team. All rights reserved.
|
||||
#
|
||||
# Redistribution and use in source and binary forms, with or without
|
||||
# modification, are permitted provided that the following conditions
|
||||
# are met:
|
||||
#
|
||||
# 1. Redistributions of source code must retain the above copyright
|
||||
# notice, this list of conditions and the following disclaimer.
|
||||
# 2. Redistributions in binary form must reproduce the above copyright
|
||||
# notice, this list of conditions and the following disclaimer in
|
||||
# the documentation and/or other materials provided with the
|
||||
# distribution.
|
||||
# 3. Neither the name PX4 nor the names of its contributors may be
|
||||
# used to endorse or promote products derived from this software
|
||||
# without specific prior written permission.
|
||||
#
|
||||
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
||||
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
||||
# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
||||
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
|
||||
# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
||||
# AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
||||
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
# POSSIBILITY OF SUCH DAMAGE.
|
||||
#
|
||||
############################################################################
|
||||
|
||||
#
|
||||
# PX4 paramers processor (main executable file)
|
||||
#
|
||||
# It scans src/ subdirectory of the project, collects all parameters
|
||||
# definitions, and outputs list of parameters in XML and DokuWiki formats.
|
||||
#
|
||||
|
||||
import scanner
|
||||
import srcparser
|
||||
import output_xml
|
||||
import output_dokuwiki_tables
|
||||
import output_dokuwiki_listings
|
||||
|
||||
# Initialize parser
|
||||
prs = srcparser.Parser()
|
||||
|
||||
# Scan directories, and parse the files
|
||||
sc = scanner.Scanner()
|
||||
sc.ScanDir("../../src", prs)
|
||||
groups = prs.GetParamGroups()
|
||||
|
||||
# Output into XML
|
||||
out = output_xml.XMLOutput(groups)
|
||||
out.Save("parameters.xml")
|
||||
|
||||
# Output to DokuWiki listings
|
||||
#out = output_dokuwiki_listings.DokuWikiListingsOutput(groups)
|
||||
#out.Save("parameters.wiki")
|
||||
|
||||
# Output to DokuWiki tables
|
||||
out = output_dokuwiki_tables.DokuWikiTablesOutput(groups)
|
||||
out.Save("parameters.wiki")
|
||||
out.SaveRpc("parameters.wikirpc.xml")
|
|
@ -44,6 +44,7 @@ class Parameter(object):
|
|||
"default": 6,
|
||||
"min": 5,
|
||||
"max": 4,
|
||||
"unit": 3,
|
||||
# all others == 0 (sorted alphabetically)
|
||||
}
|
||||
|
||||
|
@ -71,7 +72,7 @@ class Parameter(object):
|
|||
"""
|
||||
return self.fields.get(code)
|
||||
|
||||
class Parser(object):
|
||||
class SourceParser(object):
|
||||
"""
|
||||
Parses provided data and stores all found parameters internally.
|
||||
"""
|
||||
|
@ -86,7 +87,7 @@ class Parser(object):
|
|||
re_is_a_number = re.compile(r'^-?[0-9\.]')
|
||||
re_remove_dots = re.compile(r'\.+$')
|
||||
|
||||
valid_tags = set(["min", "max", "group"])
|
||||
valid_tags = set(["group", "min", "max", "unit"])
|
||||
|
||||
# Order of parameter groups
|
||||
priority = {
|
||||
|
|
|
@ -2,26 +2,21 @@ import os
|
|||
import re
|
||||
import codecs
|
||||
|
||||
class Scanner(object):
|
||||
class SourceScanner(object):
|
||||
"""
|
||||
Traverses directory tree, reads all source files, and passes their contents
|
||||
to the Parser.
|
||||
"""
|
||||
|
||||
re_file_extension = re.compile(r'\.([^\.]+)$')
|
||||
|
||||
def ScanDir(self, srcdir, parser):
|
||||
"""
|
||||
Scans provided path and passes all found contents to the parser using
|
||||
parser.Parse method.
|
||||
"""
|
||||
extensions = set(parser.GetSupportedExtensions())
|
||||
extensions = tuple(parser.GetSupportedExtensions())
|
||||
for dirname, dirnames, filenames in os.walk(srcdir):
|
||||
for filename in filenames:
|
||||
m = self.re_file_extension.search(filename)
|
||||
if m:
|
||||
ext = m.group(1)
|
||||
if ext in extensions:
|
||||
if filename.endswith(extensions):
|
||||
path = os.path.join(dirname, filename)
|
||||
self.ScanFile(path, parser)
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
python px_process_params.py
|
||||
|
||||
rm cookies.txt
|
||||
curl --cookie cookies.txt --cookie-jar cookies.txt --user-agent Mozilla/4.0 --data "u=$XMLRPCUSER&p=$XMLRPCPASS" https://pixhawk.org/start?do=login
|
||||
curl -k --cookie cookies.txt -H "Content-Type: application/xml" -X POST --data-binary @parameters.wikirpc.xml "https://pixhawk.org/lib/exe/xmlrpc.php"
|
|
@ -0,0 +1,140 @@
|
|||
#!/usr/bin/env python
|
||||
############################################################################
|
||||
#
|
||||
# Copyright (C) 2013-2014 PX4 Development Team. All rights reserved.
|
||||
#
|
||||
# Redistribution and use in source and binary forms, with or without
|
||||
# modification, are permitted provided that the following conditions
|
||||
# are met:
|
||||
#
|
||||
# 1. Redistributions of source code must retain the above copyright
|
||||
# notice, this list of conditions and the following disclaimer.
|
||||
# 2. Redistributions in binary form must reproduce the above copyright
|
||||
# notice, this list of conditions and the following disclaimer in
|
||||
# the documentation and/or other materials provided with the
|
||||
# distribution.
|
||||
# 3. Neither the name PX4 nor the names of its contributors may be
|
||||
# used to endorse or promote products derived from this software
|
||||
# without specific prior written permission.
|
||||
#
|
||||
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
||||
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
||||
# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
||||
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
|
||||
# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
||||
# AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
||||
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
# POSSIBILITY OF SUCH DAMAGE.
|
||||
#
|
||||
############################################################################
|
||||
|
||||
#
|
||||
# PX4 paramers processor (main executable file)
|
||||
#
|
||||
# This tool scans the PX4 source code for declarations of tunable parameters
|
||||
# and outputs the list in various formats.
|
||||
#
|
||||
# Currently supported formats are:
|
||||
# * XML for the parametric UI generator
|
||||
# * Human-readable description in DokuWiki page format
|
||||
#
|
||||
# This tool also allows to automatically upload the human-readable version
|
||||
# to the DokuWiki installation via XML-RPC.
|
||||
#
|
||||
|
||||
from __future__ import print_function
|
||||
import sys
|
||||
import os
|
||||
import argparse
|
||||
from px4params import srcscanner, srcparser, xmlout, dokuwikiout, dokuwikirpc
|
||||
|
||||
def main():
|
||||
# Parse command line arguments
|
||||
parser = argparse.ArgumentParser(description="Process parameter documentation.")
|
||||
parser.add_argument("-s", "--src-path",
|
||||
default="../src",
|
||||
metavar="PATH",
|
||||
help="path to source files to scan for parameters")
|
||||
parser.add_argument("-x", "--xml",
|
||||
nargs='?',
|
||||
const="parameters.xml",
|
||||
metavar="FILENAME",
|
||||
help="Create XML file"
|
||||
" (default FILENAME: parameters.xml)")
|
||||
parser.add_argument("-w", "--wiki",
|
||||
nargs='?',
|
||||
const="parameters.wiki",
|
||||
metavar="FILENAME",
|
||||
help="Create DokuWiki file"
|
||||
" (default FILENAME: parameters.wiki)")
|
||||
parser.add_argument("-u", "--wiki-update",
|
||||
nargs='?',
|
||||
const="firmware:parameters",
|
||||
metavar="PAGENAME",
|
||||
help="Update DokuWiki page"
|
||||
" (default PAGENAME: firmware:parameters)")
|
||||
parser.add_argument("--wiki-url",
|
||||
default="https://pixhawk.org",
|
||||
metavar="URL",
|
||||
help="DokuWiki URL"
|
||||
" (default: https://pixhawk.org)")
|
||||
parser.add_argument("--wiki-user",
|
||||
default=os.environ.get('XMLRPCUSER', None),
|
||||
metavar="USERNAME",
|
||||
help="DokuWiki XML-RPC user name"
|
||||
" (default: $XMLRPCUSER environment variable)")
|
||||
parser.add_argument("--wiki-pass",
|
||||
default=os.environ.get('XMLRPCPASS', None),
|
||||
metavar="PASSWORD",
|
||||
help="DokuWiki XML-RPC user password"
|
||||
" (default: $XMLRPCUSER environment variable)")
|
||||
parser.add_argument("--wiki-summary",
|
||||
metavar="SUMMARY",
|
||||
default="Automagically updated parameter documentation from code.",
|
||||
help="DokuWiki page edit summary")
|
||||
args = parser.parse_args()
|
||||
|
||||
# Check for valid command
|
||||
if not (args.xml or args.wiki or args.wiki_update):
|
||||
print("Error: You need to specify at least one output method!\n")
|
||||
parser.print_usage()
|
||||
sys.exit(1)
|
||||
|
||||
# Initialize source scanner and parser
|
||||
scanner = srcscanner.SourceScanner()
|
||||
parser = srcparser.SourceParser()
|
||||
|
||||
# Scan directories, and parse the files
|
||||
print("Scanning source path " + args.src_path)
|
||||
scanner.ScanDir(args.src_path, parser)
|
||||
param_groups = parser.GetParamGroups()
|
||||
|
||||
# Output to XML file
|
||||
if args.xml:
|
||||
print("Creating XML file " + args.xml)
|
||||
out = xmlout.XMLOutput(param_groups)
|
||||
out.Save(args.xml)
|
||||
|
||||
# Output to DokuWiki tables
|
||||
if args.wiki or args.wiki_update:
|
||||
out = dokuwikiout.DokuWikiTablesOutput(param_groups)
|
||||
if args.wiki:
|
||||
print("Creating wiki file " + args.wiki)
|
||||
out.Save(args.wiki)
|
||||
if args.wiki_update:
|
||||
if args.wiki_user and args.wiki_pass:
|
||||
print("Updating wiki page " + args.wiki_update)
|
||||
xmlrpc = dokuwikirpc.get_xmlrpc(args.wiki_url, args.wiki_user, args.wiki_pass)
|
||||
xmlrpc.wiki.putPage(args.wiki_update, out.output, {'sum': args.wiki_summary})
|
||||
else:
|
||||
print("Error: You need to specify DokuWiki XML-RPC username and password!")
|
||||
|
||||
print("All done!")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
|
@ -0,0 +1,2 @@
|
|||
# Remember to set the XMLRPCUSER and XMLRPCPASS environment variables
|
||||
python px_process_params.py --wiki-update
|
Loading…
Reference in New Issue