From 90f52bf990791ea73479ffc50fc1eb3450de443a Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Mon, 12 Sep 2016 08:55:13 -0400 Subject: Refactor pre-Doxy siphon scripts; VPP-396 - Modularize the code to make the Siphon process easier to maintain. - Move much of the output rendering into Jinja2 templates. - Add syscfg siphon type for startup config documentation. - Add sample syscfg documentation. - Add clicfg and syscfg preamble docs, adapted from their wiki pages. - Fix sorting of CLI items across multiple directories. Change-Id: Ib8288fe005adfea68ceed75a38ff8eba25d3cc79 Signed-off-by: Chris Luke --- doxygen/siphon/__init__.py | 24 +++ doxygen/siphon/generate.py | 304 ++++++++++++++++++++++++++++++++++++++ doxygen/siphon/generate_clicmd.py | 22 +++ doxygen/siphon/generate_syscfg.py | 22 +++ doxygen/siphon/parsers.py | 149 +++++++++++++++++++ doxygen/siphon/process.py | 271 +++++++++++++++++++++++++++++++++ doxygen/siphon/process_clicmd.py | 56 +++++++ doxygen/siphon/process_syscfg.py | 30 ++++ 8 files changed, 878 insertions(+) create mode 100644 doxygen/siphon/__init__.py create mode 100644 doxygen/siphon/generate.py create mode 100644 doxygen/siphon/generate_clicmd.py create mode 100644 doxygen/siphon/generate_syscfg.py create mode 100644 doxygen/siphon/parsers.py create mode 100644 doxygen/siphon/process.py create mode 100644 doxygen/siphon/process_clicmd.py create mode 100644 doxygen/siphon/process_syscfg.py (limited to 'doxygen/siphon') diff --git a/doxygen/siphon/__init__.py b/doxygen/siphon/__init__.py new file mode 100644 index 00000000..437a1df1 --- /dev/null +++ b/doxygen/siphon/__init__.py @@ -0,0 +1,24 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Siphon classes + +import generate +import generate_clicmd +import generate_syscfg + +import parsers +import process +import process_clicmd +import process_syscfg diff --git a/doxygen/siphon/generate.py b/doxygen/siphon/generate.py new file mode 100644 index 00000000..d6b6faf3 --- /dev/null +++ b/doxygen/siphon/generate.py @@ -0,0 +1,304 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Generate .siphon source fragments for later processing + +import logging +import os, sys, re, json + +"""List of (regexp, siphon_name) tuples for matching the start of C + initializer blocks in source files. Each siphon class registers + themselves on tihs list.""" +siphon_patterns = [] + +class Generate(object): + """Matches a siphon comment block start""" + siphon_block_start = re.compile("^\s*/\*\?\s*(.*)$") + + """Matches a siphon comment block stop""" + siphon_block_stop = re.compile("^(.*)\s*\?\*/\s*$") + + """Siphon block directive delimiter""" + siphon_block_delimiter = "%%" + + """Matches a siphon block directive such as + '%clicmd:group_label Debug CLI%'""" + siphon_block_directive = re.compile("(%s)\s*([a-zA-Z0-9_:]+)\s+(.*)\s*(%s)" % \ + (siphon_block_delimiter, siphon_block_delimiter)) + + """Matches the start of an initializer block""" + siphon_initializer = re.compile("\s*=") + + """Collated output for each siphon""" + output = None + + """Directory prefix to strip from input filenames to keep things tidy.""" + input_prefix = None + + """List of known siphons""" + known_siphons = None + + """Logging handler""" + log = None + + + def __init__(self, output_directory, input_prefix): + super(Generate, self).__init__() + self.log = logging.getLogger("siphon.generate") + + # Build a list of known siphons + self.known_siphons = [] + for item in siphon_patterns: + siphon = item[1] + if siphon not in self.known_siphons: + self.known_siphons.append(siphon) + + # Setup information for siphons we know about + self.output = {} + for siphon in self.known_siphons: + self.output[siphon] = { + "file": "%s/%s.siphon" % (output_directory, siphon), + "global": {}, + "items": [], + } + + self.input_prefix = input_prefix + + + """ + count open and close braces in str + return (0, index) when braces were found and count becomes 0. + index indicates the position at which the last closing brace was + found. + return (-1, -1) if a closing brace is found before any opening one. + return (count, -1) if not all opening braces are closed, count is the + current depth + """ + def count_braces(self, str, count=0, found=False): + for index in range(0, len(str)): + if str[index] == '{': + count += 1; + found = True + elif str[index] == '}': + if count == 0: + # means we never found an open brace + return (-1, -1) + count -= 1; + + if count == 0 and found: + return (count, index) + + return (count, -1) + + def parse(self, filename): + # Strip the current directory off the start of the + # filename for brevity + if filename[0:len(self.input_prefix)] == self.input_prefix: + filename = filename[len(self.input_prefix):] + if filename[0] == "/": + filename = filename[1:] + + # Work out the abbreviated directory name + directory = os.path.dirname(filename) + if directory[0:2] == "./": + directory = directory[2:] + elif directory[0:len(self.input_prefix)] == self.input_prefix: + directory = directory[len(self.input_prefix):] + if directory[0] == "/": + directory = directory[1:] + + # Open the file and explore its contents... + self.log.info("Siphoning from %s." % filename) + directives = {} + with open(filename) as fd: + siphon = None + close_siphon = None + siphon_block = "" + in_block = False + line_num = 0 + siphon_line = 0 + + for line in fd: + line_num += 1 + str = line[:-1] # filter \n + + """See if there is a block directive and if so extract it""" + def process_block_directive(str, directives): + m = self.siphon_block_directive.search(str) + if m is not None: + k = m.group(2) + v = m.group(3).strip() + directives[k] = v + # Return only the parts we did not match + return str[0:m.start(1)] + str[m.end(4):] + + return str + + def process_block_prefix(str): + if str.startswith(" * "): + str = str[3:] + elif str == " *": + str = "" + return str + + if not in_block: + # See if the line contains the start of a siphon doc block + m = self.siphon_block_start.search(str) + if m is not None: + in_block = True + t = m.group(1) + + # Now check if the block closes on the same line + m = self.siphon_block_stop.search(t) + if m is not None: + t = m.group(1) + in_block = False + + # Check for directives + t = process_block_directive(t, directives) + + # Filter for normal comment prefixes + t = process_block_prefix(t) + + # Add what is left + siphon_block += t + + # Skip to next line + continue + + else: + # Check to see if we have an end block marker + m = self.siphon_block_stop.search(str) + if m is not None: + in_block = False + t = m.group(1) + else: + t = str + + # Check for directives + t = process_block_directive(t, directives) + + # Filter for normal comment prefixes + t = process_block_prefix(t) + + # Add what is left + siphon_block += t + "\n" + + # Skip to next line + continue + + + if siphon is None: + # Look for blocks we need to siphon + for p in siphon_patterns: + if p[0].match(str): + siphon = [ p[1], str + "\n", 0 ] + siphon_line = line_num + + # see if we have an initializer + m = self.siphon_initializer.search(str) + if m is not None: + # count the braces on this line + (count, index) = \ + self.count_braces(str[m.start():]) + siphon[2] = count + # TODO - it's possible we have the + # initializer all on the first line + # we should check for it, but also + # account for the possibility that + # the open brace is on the next line + #if count == 0: + # # braces balanced + # close_siphon = siphon + # siphon = None + else: + # no initializer: close the siphon right now + close_siphon = siphon + siphon = None + else: + # See if we should end the siphon here - do we have + # balanced braces? + (count, index) = self.count_braces(str, + count=siphon[2], found=True) + if count == 0: + # braces balanced - add the substring and + # close the siphon + siphon[1] += str[:index+1] + ";\n" + close_siphon = siphon + siphon = None + else: + # add the whole string, move on + siphon[2] = count + siphon[1] += str + "\n" + + if close_siphon is not None: + # Write the siphoned contents to the right place + siphon_name = close_siphon[0] + + # Copy directives for the file + details = {} + for key in directives: + if ":" in key: + (sn, label) = key.split(":") + if sn == siphon_name: + details[label] = directives[key] + else: + details[key] = directives[key] + + # Copy details for this block + details['file'] = filename + details['directory'] = directory + details['line_start'] = siphon_line + details['line_end'] = line_num + details['siphon_block'] = siphon_block.strip() + details["block"] = close_siphon[1] + + # Store the item + self.output[siphon_name]['items'].append(details) + + # All done + close_siphon = None + siphon_block = "" + + # Update globals + for key in directives.keys(): + if ':' not in key: + continue + + if filename.endswith("/dir.dox"): + # very special! use the parent directory name + l = directory + else: + l = filename + + (sn, label) = key.split(":") + + if sn not in self.output: + self.output[sn] = {} + if 'global' not in self.output[sn]: + self.output[sn]['global'] = {} + if l not in self.output[sn]['global']: + self.output[sn]['global'][l] = {} + + self.output[sn]['global'][l][label] = directives[key] + + def deliver(self): + # Write out the data + for siphon in self.output.keys(): + self.log.info("Saving siphon data %s." % siphon) + s = self.output[siphon] + with open(s['file'], "a") as fp: + json.dump(s, fp, + separators=(',', ': '), indent=4, sort_keys=True) + diff --git a/doxygen/siphon/generate_clicmd.py b/doxygen/siphon/generate_clicmd.py new file mode 100644 index 00000000..7b131110 --- /dev/null +++ b/doxygen/siphon/generate_clicmd.py @@ -0,0 +1,22 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import generate, re + +# Register our regexp +generate.siphon_patterns.append(( + re.compile("(?PVLIB_CLI_COMMAND)\s*" + "[(](?P[a-zA-Z0-9_]+)(,[^)]*)?[)]"), + "clicmd" +)) diff --git a/doxygen/siphon/generate_syscfg.py b/doxygen/siphon/generate_syscfg.py new file mode 100644 index 00000000..c77936a9 --- /dev/null +++ b/doxygen/siphon/generate_syscfg.py @@ -0,0 +1,22 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import generate, re + +# Register our regexp +generate.siphon_patterns.append(( + re.compile("(?PVLIB_CONFIG_FUNCTION)\s*" + '[(](?P[a-zA-Z0-9_]+)\s*,\s*"(?P[^"]*)"[)]'), + "syscfg" +)) diff --git a/doxygen/siphon/parsers.py b/doxygen/siphon/parsers.py new file mode 100644 index 00000000..6fe8600d --- /dev/null +++ b/doxygen/siphon/parsers.py @@ -0,0 +1,149 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import cgi, pyparsing as pp + +# Some useful primitives +ident = pp.Word(pp.alphas + "_", pp.alphas + pp.nums + "_") +intNum = pp.Word(pp.nums) +hexNum = pp.Literal("0x") + pp.Word(pp.hexnums) +octalNum = pp.Literal("0") + pp.Word("01234567") +integer = (hexNum | octalNum | intNum) + \ + pp.Optional(pp.Literal("ULL") | pp.Literal("LL") | pp.Literal("L")) +floatNum = pp.Regex(r'\d+(\.\d*)?([eE]\d+)?') + pp.Optional(pp.Literal("f")) +char = pp.Literal("'") + pp.Word(pp.printables, exact=1) + pp.Literal("'") +arrayIndex = integer | ident + +lbracket = pp.Literal("(").suppress() +rbracket = pp.Literal(")").suppress() +lbrace = pp.Literal("{").suppress() +rbrace = pp.Literal("}").suppress() +comma = pp.Literal(",").suppress() +equals = pp.Literal("=").suppress() +dot = pp.Literal(".").suppress() +semicolon = pp.Literal(";").suppress() + +# initializer := { [member = ] (variable | expression | { initializer } ) } +typeName = ident +varName = ident +typeSpec = pp.Optional("unsigned") + \ + pp.oneOf("int long short float double char u8 i8 void") + \ + pp.Optional(pp.Word("*"), default="") +typeCast = pp.Combine( "(" + ( typeSpec | typeName ) + ")" ).suppress() + +string = pp.Combine(pp.OneOrMore(pp.QuotedString(quoteChar='"', + escChar='\\', multiline=True)), adjacent=False) +literal = pp.Optional(typeCast) + (integer | floatNum | char | string) +var = pp.Combine(pp.Optional(typeCast) + varName + + pp.Optional("[" + arrayIndex + "]")) + +# This could be more complete, but suffices for our uses +expr = (literal | var) + +"""Parse and render a block of text into a Python dictionary.""" +class Parser(object): + """Compiled PyParsing BNF""" + _parser = None + + def __init__(self): + super(Parser, self).__init__() + self._parser = self.BNF() + + def BNF(self): + raise NotImplementedError + + def item(self, item): + raise NotImplementedError + + def parse(self, input): + item = self._parser.parseString(input).asList() + return self.item(item) + + +"""Parser for function-like macros - without the closing semi-colon.""" +class ParserFunctionMacro(Parser): + def BNF(self): + # VLIB_CONFIG_FUNCTION (unix_config, "unix") + macroName = ident + params = pp.Group(pp.ZeroOrMore(expr + comma) + expr) + macroParams = lbracket + params + rbracket + + return macroName + macroParams + + def item(self, item): + r = { + "macro": item[0], + "name": item[1][1], + "function": item[1][0], + } + + return r + + +"""Parser for function-like macros with a closing semi-colon.""" +class ParseFunctionMacroStmt(ParserFunctionMacro): + def BNF(self): + # VLIB_CONFIG_FUNCTION (unix_config, "unix"); + function_macro = super(ParseFunctionMacroStmt, self).BNF() + mi = function_macro + semicolon + mi.ignore(pp.cppStyleComment) + + return mi + + +""" +Parser for our struct initializers which are composed from a +function-like macro, equals sign, and then a normal C struct initalizer +block. +""" +class MacroInitializer(ParserFunctionMacro): + def BNF(self): + # VLIB_CLI_COMMAND (show_sr_tunnel_command, static) = { + # .path = "show sr tunnel", + # .short_help = "show sr tunnel [name ]", + # .function = show_sr_tunnel_fn, + # }; + cs = pp.Forward() + + + member = pp.Combine(dot + varName + pp.Optional("[" + arrayIndex + "]"), + adjacent=False) + value = (expr | cs) + + entry = pp.Group(pp.Optional(member + equals, default="") + value) + entries = (pp.ZeroOrMore(entry + comma) + entry + pp.Optional(comma)) | \ + (pp.ZeroOrMore(entry + comma)) + + cs << (lbrace + entries + rbrace) + + macroName = ident + params = pp.Group(pp.ZeroOrMore(expr + comma) + expr) + macroParams = lbracket + params + rbracket + + function_macro = super(MacroInitializer, self).BNF() + mi = function_macro + equals + pp.Group(cs) + semicolon + mi.ignore(pp.cppStyleComment) + + return mi + + def item(self, item): + r = { + "macro": item[0], + "name": item[1][0], + "params": item[2], + "value": {}, + } + + for param in item[2]: + r["value"][param[0]] = cgi.escape(param[1]) + + return r diff --git a/doxygen/siphon/process.py b/doxygen/siphon/process.py new file mode 100644 index 00000000..c7f8f1a2 --- /dev/null +++ b/doxygen/siphon/process.py @@ -0,0 +1,271 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Generation template class + +import logging, os,sys, cgi, json, jinja2, HTMLParser + +# Classes register themselves in this dictionary +"""Mapping of known processors to their classes""" +siphons = {} + + +"""Generate rendered output for siphoned data.""" +class Siphon(object): + + # Set by subclasses + """Our siphon name""" + name = None + + # Set by subclasses + """Name of an identifier used by this siphon""" + identifier = None + + # Set by subclasses + """The pyparsing object to use to parse with""" + _parser = None + + """The input data""" + _cmds = None + + """Group key to (directory,file) mapping""" + _group = None + + """Logging handler""" + log = None + + """Directory to look for siphon rendering templates""" + template_directory = None + + """Template environment, if we're using templates""" + _tplenv = None + + def __init__(self, template_directory=None): + super(Siphon, self).__init__() + self.log = logging.getLogger("siphon.process.%s" % self.name) + + if template_directory is not None: + self.template_directory = template_directory + searchpath = [ + template_directory + "/" + self.name, + template_directory + "/" + "default", + ] + loader = jinja2.FileSystemLoader(searchpath=searchpath) + self._tplenv = jinja2.Environment( + loader=loader, + trim_blocks=True, + keep_trailing_newline=True) + + # Convenience, get a reference to the internal escape and + # unescape methods in cgi and HTMLParser. These then become + # available to templates to use, if needed. + self._h = HTMLParser.HTMLParser() + self.escape = cgi.escape + self.unescape = self._h.unescape + + + # Output renderers + + """Returns an object to be used as the sorting key in the item index.""" + def index_sort_key(self, group): + return group + + """Returns a string to use as the header at the top of the item index.""" + def index_header(self): + return self.template("index_header") + + """Returns the string fragment to use for each section in the item + index.""" + def index_section(self, group): + return self.template("index_section", group=group) + + """Returns the string fragment to use for each entry in the item index.""" + def index_entry(self, meta, item): + return self.template("index_entry", meta=meta, item=item) + + """Returns an object, typically a string, to be used as the sorting key + for items within a section.""" + def item_sort_key(self, item): + return item['name'] + + """Returns a key for grouping items together.""" + def group_key(self, directory, file, macro, name): + _global = self._cmds['_global'] + + if file in _global and 'group_label' in _global[file]: + self._group[file] = (directory, file) + return file + + self._group[directory] = (directory, None) + return directory + + """Returns a key for identifying items within a grouping.""" + def item_key(self, directory, file, macro, name): + return name + + """Returns a string to use as the header when rendering the item.""" + def item_header(self, group): + return self.template("item_header", group=group) + + """Returns a string to use as the body when rendering the item.""" + def item_format(self, meta, item): + return self.template("item_format", meta=meta, item=item) + + """Returns a string to use as the label for the page reference.""" + def page_label(self, group): + return "_".join(( + self.name, + self.sanitize_label(group) + )) + + """Returns a title to use for a page.""" + def page_title(self, group): + _global = self._cmds['_global'] + (directory, file) = self._group[group] + + if file and file in _global and 'group_label' in _global[file]: + return _global[file]['group_label'] + + if directory in _global and 'group_label' in _global[directory]: + return _global[directory]['group_label'] + + return directory + + """Returns a string to use as the label for the section reference.""" + def item_label(self, group, item): + return "__".join(( + self.name, + item + )) + + """Label sanitizer; for creating Doxygen references""" + def sanitize_label(self, value): + return value.replace(" ", "_") \ + .replace("/", "_") \ + .replace(".", "_") + + """Template processor""" + def template(self, name, **kwargs): + tpl = self._tplenv.get_template(name + ".md") + return tpl.render( + this=self, + **kwargs) + + + # Processing methods + + """Parse the input file into a more usable dictionary structure.""" + def load_json(self, files): + self._cmds = {} + self._group = {} + + line_num = 0 + line_start = 0 + for filename in files: + filename = os.path.relpath(filename) + self.log.info("Parsing items in file \"%s\"." % filename) + data = None + with open(filename, "r") as fd: + data = json.load(fd) + + self._cmds['_global'] = data['global'] + + # iterate the items loaded and regroup it + for item in data["items"]: + try: + o = self._parser.parse(item['block']) + except: + self.log.error("Exception parsing item: %s\n%s" \ + % (json.dumps(item, separators=(',', ': '), + indent=4), + item['block'])) + raise + + # Augment the item with metadata + o["meta"] = {} + for key in item: + if key == 'block': + continue + o['meta'][key] = item[key] + + # Load some interesting fields + directory = item['directory'] + file = item['file'] + macro = o["macro"] + name = o["name"] + + # Generate keys to group items by + group_key = self.group_key(directory, file, macro, name) + item_key = self.item_key(directory, file, macro, name) + + if group_key not in self._cmds: + self._cmds[group_key] = {} + + self._cmds[group_key][item_key] = o + + """Iterate over the input data, calling render methods to generate the + output.""" + def process(self, out=None): + + if out is None: + out = sys.stdout + + # Accumulated body contents + contents = "" + + # Write the header for this siphon type + out.write(self.index_header()) + + # Sort key helper for the index + def group_sort_key(group): + return self.index_sort_key(group) + + # Iterate the dictionary and process it + for group in sorted(self._cmds.keys(), key=group_sort_key): + if group.startswith('_'): + continue + + self.log.info("Processing items in group \"%s\" (%s)." % \ + (group, group_sort_key(group))) + + # Generate the section index entry (write it now) + out.write(self.index_section(group)) + + # Generate the item header (save for later) + contents += self.item_header(group) + + def item_sort_key(key): + return self.item_sort_key(self._cmds[group][key]) + + for key in sorted(self._cmds[group].keys(), key=item_sort_key): + self.log.debug("--- Processing key \"%s\" (%s)." % \ + (key, item_sort_key(key))) + + o = self._cmds[group][key] + meta = { + "directory": o['meta']['directory'], + "file": o['meta']['file'], + "macro": o['macro'], + "key": key, + "label": self.item_label(group, key), + } + + # Generate the index entry for the item (write it now) + out.write(self.index_entry(meta, o)) + + # Generate the item itself (save for later) + contents += self.item_format(meta, o) + + # Deliver the accumulated body output + out.write(contents) diff --git a/doxygen/siphon/process_clicmd.py b/doxygen/siphon/process_clicmd.py new file mode 100644 index 00000000..9b3bd35c --- /dev/null +++ b/doxygen/siphon/process_clicmd.py @@ -0,0 +1,56 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Generate clicmd formatted output + +import process, parsers + +class SiphonCLICMD(process.Siphon): + + name = "clicmd" + identifier = "VLIB_CLI_COMMAND" + + def __init__(self, *args, **kwargs): + super(SiphonCLICMD, self).__init__(*args, **kwargs) + self._parser = parsers.MacroInitializer() + + + # Output renderers + + def index_sort_key(self, group): + _global = self._cmds['_global'] + if group not in self._group: + return group + (directory, file) = self._group[group] + + if file in _global and 'group_label' in _global[file]: + return _global[file]['group_label'] + + if directory in _global and 'group_label' in _global[directory]: + return _global[directory]['group_label'] + + return group + + def item_sort_key(self, item): + return item['value']['path'] + + def item_label(self, group, item): + return "_".join(( + self.name, + self.sanitize_label(self._cmds[group][item]['value']['path']) + )) + + +# Register our processor +process.siphons["clicmd"] = SiphonCLICMD diff --git a/doxygen/siphon/process_syscfg.py b/doxygen/siphon/process_syscfg.py new file mode 100644 index 00000000..94be5910 --- /dev/null +++ b/doxygen/siphon/process_syscfg.py @@ -0,0 +1,30 @@ +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Generate syscfg formatted output + +import process, parsers + +class SiphonSYSCFG(process.Siphon): + + name = "syscfg" + identifier = "VLIB_CONFIG_FUNCTION" + + def __init__(self, *args, **kwargs): + super(SiphonSYSCFG, self).__init__(*args, **kwargs) + self._parser = parsers.ParseFunctionMacroStmt() + + +# Register our processor +process.siphons["syscfg"] = SiphonSYSCFG -- cgit 1.2.3-korg From af405f77c74d8b41523d4e7f39a91c7aec2fd93c Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Mon, 26 Sep 2016 15:51:56 -0700 Subject: Fix missing output in generated CLI/config The templates were looking for the name of the CLI_COMMAND and CONFIG_FUNCTION structures in the srong place. Change-Id: I709d6716216173ba6a7ed41a260728238f96d2db Signed-off-by: Chris Luke --- doxygen/siphon/process.py | 1 + doxygen/siphon_templates/clicmd/item_format.md | 8 ++++---- doxygen/siphon_templates/syscfg/item_format.md | 6 +++--- 3 files changed, 8 insertions(+), 7 deletions(-) (limited to 'doxygen/siphon') diff --git a/doxygen/siphon/process.py b/doxygen/siphon/process.py index c7f8f1a2..34e829c5 100644 --- a/doxygen/siphon/process.py +++ b/doxygen/siphon/process.py @@ -257,6 +257,7 @@ class Siphon(object): "directory": o['meta']['directory'], "file": o['meta']['file'], "macro": o['macro'], + "name": o['name'], "key": key, "label": self.item_label(group, key), } diff --git a/doxygen/siphon_templates/clicmd/item_format.md b/doxygen/siphon_templates/clicmd/item_format.md index 77d0484b..288dae40 100644 --- a/doxygen/siphon_templates/clicmd/item_format.md +++ b/doxygen/siphon_templates/clicmd/item_format.md @@ -31,7 +31,7 @@ ### Long help {{ v['long_help'] }} -{%- endif %} +{% endif %} {% if 'siphon_block' in item['meta'] %} {% set sb = item["meta"]["siphon_block"] %} {% if sb %} @@ -42,14 +42,14 @@ {{ sb }} {% endif %} {% endif %} -{% if "item" in meta or "function" in v %} +{% if 'name' in meta or 'function' in v %} {# Gives some developer-useful linking #} ### Declaration and implementation -{% if "item" in meta %} +{% if "name" in meta %} {{ "Declaration: @ref %s (@ref %s line %d)" % - (meta['item'], meta["file"], item["meta"]["line_start"]) }} + (meta['name'], meta["file"], item["meta"]["line_start"]) }} {% endif %} {% if "function" in v %} diff --git a/doxygen/siphon_templates/syscfg/item_format.md b/doxygen/siphon_templates/syscfg/item_format.md index 5d3bb5c8..53136115 100644 --- a/doxygen/siphon_templates/syscfg/item_format.md +++ b/doxygen/siphon_templates/syscfg/item_format.md @@ -25,14 +25,14 @@ {{ sb }} {% endif %} {% endif %} -{% if "item" in meta or "function" in item %} +{% if "name" in meta or "function" in item %} {# Gives some developer-useful linking #} ### Declaration and implementation -{% if "item" in meta %} +{% if "name" in meta %} {{ "Declaration: @ref %s (@ref %s line %d)" % - (meta['item'], meta["file"], item["meta"]["line_start"]) }} + (meta['name'], meta["file"], item["meta"]["line_start"]) }} {% endif %} {% if "function" in item %} -- cgit 1.2.3-korg From c3f92adf6be41263eb466e074e4136d29b50b59a Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Wed, 5 Oct 2016 15:45:19 -0400 Subject: Add support for using documentation siphons in multiple ways Experiental support for generating multiple output formats from the same siphoned data. Adds a contrived example to generate a plain list of all CLI commands (the "itemlist" format). Eventually we can consider moving the tempate procesisng into the Output class as well as a way to override how the data is traversed (ordered). Change-Id: I77629a74a8fa0c7e583993469dc50491f72f13e7 Signed-off-by: Chris Luke --- doxygen/Makefile | 36 ++++-- doxygen/siphon-process | 6 +- doxygen/siphon/process.py | 79 +++++++++---- doxygen/siphon_templates/clicmd/index_entry.md | 17 --- doxygen/siphon_templates/clicmd/index_header.md | 130 --------------------- doxygen/siphon_templates/clicmd/item_format.md | 59 ---------- doxygen/siphon_templates/default/index_entry.md | 16 --- doxygen/siphon_templates/default/index_section.md | 18 --- doxygen/siphon_templates/default/item_format.md | 16 --- doxygen/siphon_templates/default/item_header.md | 18 --- .../itemlist/clicmd/item_format.itemlist | 17 +++ .../itemlist/default/index_entry.itemlist | 15 +++ .../itemlist/default/index_header.itemlist | 15 +++ .../itemlist/default/index_section.itemlist | 15 +++ .../itemlist/default/item_format.itemlist | 16 +++ .../itemlist/default/item_header.itemlist | 15 +++ .../itemlist/syscfg/item_format.itemlist | 17 +++ .../markdown/clicmd/index_entry.md | 17 +++ .../markdown/clicmd/index_header.md | 130 +++++++++++++++++++++ .../markdown/clicmd/item_format.md | 59 ++++++++++ .../markdown/default/index_entry.md | 16 +++ .../markdown/default/index_section.md | 18 +++ .../markdown/default/item_format.md | 16 +++ .../markdown/default/item_header.md | 18 +++ .../markdown/syscfg/index_header.md | 111 ++++++++++++++++++ .../markdown/syscfg/item_format.md | 42 +++++++ doxygen/siphon_templates/syscfg/index_header.md | 111 ------------------ doxygen/siphon_templates/syscfg/item_format.md | 42 ------- 28 files changed, 626 insertions(+), 459 deletions(-) delete mode 100644 doxygen/siphon_templates/clicmd/index_entry.md delete mode 100644 doxygen/siphon_templates/clicmd/index_header.md delete mode 100644 doxygen/siphon_templates/clicmd/item_format.md delete mode 100644 doxygen/siphon_templates/default/index_entry.md delete mode 100644 doxygen/siphon_templates/default/index_section.md delete mode 100644 doxygen/siphon_templates/default/item_format.md delete mode 100644 doxygen/siphon_templates/default/item_header.md create mode 100644 doxygen/siphon_templates/itemlist/clicmd/item_format.itemlist create mode 100644 doxygen/siphon_templates/itemlist/default/index_entry.itemlist create mode 100644 doxygen/siphon_templates/itemlist/default/index_header.itemlist create mode 100644 doxygen/siphon_templates/itemlist/default/index_section.itemlist create mode 100644 doxygen/siphon_templates/itemlist/default/item_format.itemlist create mode 100644 doxygen/siphon_templates/itemlist/default/item_header.itemlist create mode 100644 doxygen/siphon_templates/itemlist/syscfg/item_format.itemlist create mode 100644 doxygen/siphon_templates/markdown/clicmd/index_entry.md create mode 100644 doxygen/siphon_templates/markdown/clicmd/index_header.md create mode 100644 doxygen/siphon_templates/markdown/clicmd/item_format.md create mode 100644 doxygen/siphon_templates/markdown/default/index_entry.md create mode 100644 doxygen/siphon_templates/markdown/default/index_section.md create mode 100644 doxygen/siphon_templates/markdown/default/item_format.md create mode 100644 doxygen/siphon_templates/markdown/default/item_header.md create mode 100644 doxygen/siphon_templates/markdown/syscfg/index_header.md create mode 100644 doxygen/siphon_templates/markdown/syscfg/item_format.md delete mode 100644 doxygen/siphon_templates/syscfg/index_header.md delete mode 100644 doxygen/siphon_templates/syscfg/item_format.md (limited to 'doxygen/siphon') diff --git a/doxygen/Makefile b/doxygen/Makefile index 7031e84d..92fa3635 100644 --- a/doxygen/Makefile +++ b/doxygen/Makefile @@ -121,6 +121,7 @@ SIPHONS ?= clicmd syscfg SIPHON_FILES = $(addprefix $(SIPHON_INPUT)/,$(addsuffix .siphon,$(SIPHONS))) SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS))) +SIPHON_ITEMLIST = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .itemlist,$(filter clicmd,$(SIPHONS)))) $(BR)/.doxygen-bootstrap.ok: Makefile @echo "Checking whether dependencies for Doxygen are installed..." @@ -200,24 +201,37 @@ $(SIPHON_FILES): $(BR)/.doxygen-bootstrap.ok \ --output="$(SIPHON_INPUT)" \ "@$(SIPHON_INPUT)/files" -# Process the .siphon source fragments and render them into doxygen flavored -# markdown documentation -.DELETE_ON_ERROR: $(SIPHON_DOCS) -$(SIPHON_OUTPUT)/%.md: $(SIPHON_INPUT)/%.siphon \ +# Evaluate this to build a siphon doc output target for each desired +# output type: +# $(eval $(call siphon-process,file_extension,output_type_name)) +define siphon-process +$(SIPHON_OUTPUT)/%.$(1): $(SIPHON_INPUT)/%.siphon \ $(DOXY_DIR)/siphon-process \ $(wildcard $(DOXY_DIR)/siphon/*.py) \ - $(wildcard $(DOXY_DIR)/siphon_templates/*/*.md) - @echo "Processing siphon from $(notdir $<)..." + $(wildcard $(DOXY_DIR)/siphon_templates/$(2)/*/*.$(1)) + @echo "Processing siphon for $(2) from $$(notdir $$<)..." @set -e; \ cd "$(WS_ROOT)"; \ $(DOXY_DIR)/siphon-process \ - --type=$(basename $(notdir $<)) \ - --output="$@" \ - "$<" + --type=$$(basename $$(notdir $$<)) \ + --format=$(2) \ + --output="$$@" \ + "$$<" +endef + +# Process the .siphon source fragments and render them into doxygen flavored +# markdown documentation +.DELETE_ON_ERROR: $(SIPHON_DOCS) +$(eval $(call siphon-process,md,markdown)) + +# Process the .siphon source fragments and render them into a list of cli +# commands. +.DELETE_ON_ERROR: $(SIPHON_ITEMLIST) +$(eval $(call siphon-process,itemlist,itemlist)) -# This target can be used just to generate the siphoned docs +# This target can be used just to generate the siphoned things .PHONY: doxygen-siphon -doxygen-siphon: $(SIPHON_DOCS) +doxygen-siphon: $(SIPHON_DOCS) $(SIPHON_ITEMLIST) # Generate the doxygen docs .PHONY: doxygen diff --git a/doxygen/siphon-process b/doxygen/siphon-process index ea9df96f..698da882 100755 --- a/doxygen/siphon-process +++ b/doxygen/siphon-process @@ -23,6 +23,7 @@ import siphon DEFAULT_LOGFILE = None DEFAULT_LOGLEVEL = "info" DEFAULT_SIPHON ="clicmd" +DEFAULT_FORMAT = "markdown" DEFAULT_OUTPUT = None DEFAULT_TEMPLATES = os.path.dirname(__file__) + "/siphon_templates" @@ -36,6 +37,9 @@ ap.add_argument("--log-level", default=DEFAULT_LOGLEVEL, ap.add_argument("--type", '-t', metavar="siphon_type", default=DEFAULT_SIPHON, choices=siphon.process.siphons.keys(), help="Siphon type to process [%s]" % DEFAULT_SIPHON) +ap.add_argument("--format", '-f', default=DEFAULT_FORMAT, + choices=siphon.process.formats.keys(), + help="Output format to generate [%s]" % DEFAULT_FORMAT) ap.add_argument("--output", '-o', metavar="file", default=DEFAULT_OUTPUT, help="Output file (uses stdout if not defined) [%s]" % DEFAULT_OUTPUT) ap.add_argument("--templates", metavar="directory", default=DEFAULT_TEMPLATES, @@ -56,7 +60,7 @@ else: # Get our processor klass = siphon.process.siphons[args.type] -processor = klass(template_directory=args.templates) +processor = klass(template_directory=args.templates, format=args.format) # Load the input files processor.load_json(args.input) diff --git a/doxygen/siphon/process.py b/doxygen/siphon/process.py index 34e829c5..f3119ea8 100644 --- a/doxygen/siphon/process.py +++ b/doxygen/siphon/process.py @@ -20,6 +20,9 @@ import logging, os,sys, cgi, json, jinja2, HTMLParser """Mapping of known processors to their classes""" siphons = {} +"""Mapping of known output formats to their classes""" +formats = {} + """Generate rendered output for siphoned data.""" class Siphon(object): @@ -51,28 +54,36 @@ class Siphon(object): """Template environment, if we're using templates""" _tplenv = None - def __init__(self, template_directory=None): + def __init__(self, template_directory, format): super(Siphon, self).__init__() self.log = logging.getLogger("siphon.process.%s" % self.name) - if template_directory is not None: - self.template_directory = template_directory - searchpath = [ - template_directory + "/" + self.name, - template_directory + "/" + "default", - ] - loader = jinja2.FileSystemLoader(searchpath=searchpath) - self._tplenv = jinja2.Environment( - loader=loader, - trim_blocks=True, - keep_trailing_newline=True) - - # Convenience, get a reference to the internal escape and - # unescape methods in cgi and HTMLParser. These then become - # available to templates to use, if needed. - self._h = HTMLParser.HTMLParser() - self.escape = cgi.escape - self.unescape = self._h.unescape + # Get our output format details + fmt_klass = formats[format] + fmt = fmt_klass() + self._format = fmt + + # Sort out the template search path + def _tpldir(name): + return os.sep.join((template_directory, fmt.name, name)) + + self.template_directory = template_directory + searchpath = [ + _tpldir(self.name), + _tpldir("default"), + ] + loader = jinja2.FileSystemLoader(searchpath=searchpath) + self._tplenv = jinja2.Environment( + loader=loader, + trim_blocks=True, + keep_trailing_newline=True) + + # Convenience, get a reference to the internal escape and + # unescape methods in cgi and HTMLParser. These then become + # available to templates to use, if needed. + self._h = HTMLParser.HTMLParser() + self.escape = cgi.escape + self.unescape = self._h.unescape # Output renderers @@ -157,7 +168,7 @@ class Siphon(object): """Template processor""" def template(self, name, **kwargs): - tpl = self._tplenv.get_template(name + ".md") + tpl = self._tplenv.get_template(name + self._format.extension) return tpl.render( this=self, **kwargs) @@ -270,3 +281,31 @@ class Siphon(object): # Deliver the accumulated body output out.write(contents) + + +"""Output format class""" +class Format(object): + + """Name of this output format""" + name = None + + """Expected file extension of templates that build this format""" + extension = None + + +"""Markdown output format""" +class FormatMarkdown(Format): + name = "markdown" + extension = ".md" + +# Register 'markdown' +formats["markdown"] = FormatMarkdown + + +"""Itemlist output format""" +class FormatItemlist(Format): + name = "itemlist" + extension = ".itemlist" + +# Register 'itemlist' +formats["itemlist"] = FormatItemlist diff --git a/doxygen/siphon_templates/clicmd/index_entry.md b/doxygen/siphon_templates/clicmd/index_entry.md deleted file mode 100644 index 1fa9ec9b..00000000 --- a/doxygen/siphon_templates/clicmd/index_entry.md +++ /dev/null @@ -1,17 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -{% set v = item['value'] %} -{{ "* [%s](@ref %s)" % (v['path'], meta["label"]) }} diff --git a/doxygen/siphon_templates/clicmd/index_header.md b/doxygen/siphon_templates/clicmd/index_header.md deleted file mode 100644 index 4167f4dc..00000000 --- a/doxygen/siphon_templates/clicmd/index_header.md +++ /dev/null @@ -1,130 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -# Debug CLI {{'{#'}}clicmd} - -The VPP network stack comes equipped with a set of commands that are useful -for debugging. - -The easiest way to access the CLI (with proper permissions) is to use the -vppctl command: - -``` -sudo vppctl -``` - -The CLI parser matches static keyword strings, eventually invoking an action -function. Unambiguous partial keyword matching always occurs. The action -functions consume input until satisfied or until they fail. This model makes -for easy coding, but does not guarantee useful "help" output. It's up to the -CLI command writer to add useful help strings. - -You can find the source code of CLI commands by searching for instances of the -@c VLIB_CLI_COMMAND macro in the code source files. - -Please help maintain and improve this document to make and keep these commands -clear and useful! - -@todo Document where to modify this CLI intro text. - - -## Debug and Telnet CLI - -The debug CLI is enabled with the unix interactive parameter or startup -configuration option. This causes VPP to start without daemonizing and -presents a command line interface on the terminal where it is run. - -The Telnet CLI is enabled with the `cli-listen localhost:5002` option which -will cause VPP to listen for TCP connections on the localhost address port -@c 5002. A Telnet client can then connect to this port (for example, `telnet -localhost 5002`) and will receive a command line prompt. - -This configuration will enable both mechanisms: - -``` -unix { - interactive - cli-listen localhost:5002 -} -``` - -The debug CLI can operate in line mode, which may be useful when running -inside an IDE like Emacs. This is enabled with the option -`unix cli-line-mode`. Several other options exist that alter how this -CLI works, see the @ref syscfg section for details. - -The CLI starts with a banner graphic (which can be disabled) and a prompt. The -prompt will typically read `vpp` for a release version of VPP and `DBGvpp#` -for a development version with debugging enabled, for example: - - _______ _ _ _____ ___ - __/ __/ _ \ (_)__ | | / / _ \/ _ \ - _/ _// // / / / _ \ | |/ / ___/ ___/ - /_/ /____(_)_/\___/ |___/_/ /_/ - - vpp# - -versus: - - _______ _ _ _____ ___ - __/ __/ _ \ (_)__ | | / / _ \/ _ \ - _/ _// // / / / _ \ | |/ / ___/ ___/ - /_/ /____(_)_/\___/ |___/_/ /_/ - - DBGvpp# - -This prompt can be configured with the `unix cli-prompt` setting and the -banner is disabled with `unix cli-no-banner`. - -## CLI features - -The CLI has several editing features that make it easy to use. - -- Cursor keys left/right will move the cursor within a command line; - typing will insert at the cursor; erase will erase at the cursor. - -- Ctrl-left/right will search for the start of the next word to - the left or right. -- Home/end will jump the cursor to the start and end of the line. -- Cursor keys up/down and ^P/^N iterate through the command history - buffer. Lines from the history buffer may be edited. New commands - are added to the end of the buffer when executed; though - duplicates of the previous command are not added. -- ^U erases the line contents from the left of the cursor to the - start. -- ^K erases the contents from the cursor to the end. -- ^S/^R will search the command history forwards or in reverse for - a command; start typing for matches to auto complete. -- ^L will clear the screen (if supported by the terminal) and repaint - the prompt and any current line. The cursor position is also - retained. -- The CLI can be closed with the quit command. Alternatively, ^D on - an empty input line will also close the session. Closing the debug - session will also shutdown VPP. - -Output that exceeds the length of a terminal page will be buffered, up to a -limit. - -- Space or page-down displays the next page. -- Enter or down-arrow displays the next line. -- Page-up goes back a page. -- Up-arrow goes up a line. -- Home/end jump to the start/end of the buffered output. -- The key q quits the pager. Space and enter will also quit the - pager if the end of the buffer has been reached. - -## Index of CLI commands - -[TOC] diff --git a/doxygen/siphon_templates/clicmd/item_format.md b/doxygen/siphon_templates/clicmd/item_format.md deleted file mode 100644 index 288dae40..00000000 --- a/doxygen/siphon_templates/clicmd/item_format.md +++ /dev/null @@ -1,59 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -{% set v = item['value'] %} -{{ "@section %s %s" % (meta['label'], v['path']) }} -{% if 'short_help' in v %} - -### Summary/usage - -{% set str = v['short_help'] %} -{% set period = "." if str[-1] != "." else "" %} -{% set prefix = " " if "[" in str or "<" in str or "|" in str else "" %} -{% set str = this.unescape(str) %} -{{ "%s%s%s" % (prefix, str, period) }} -{% endif %} -{% if 'long_help' in v %} -{# This is seldom used and will likely be deprecated #} - -### Long help - -{{ v['long_help'] }} -{% endif %} -{% if 'siphon_block' in item['meta'] %} -{% set sb = item["meta"]["siphon_block"] %} -{% if sb %} -{# Extracted from the code in /*? ... ?*/ blocks #} - -### Description - -{{ sb }} -{% endif %} -{% endif %} -{% if 'name' in meta or 'function' in v %} -{# Gives some developer-useful linking #} - -### Declaration and implementation -{% if "name" in meta %} - -{{ "Declaration: @ref %s (@ref %s line %d)" % - (meta['name'], meta["file"], item["meta"]["line_start"]) }} -{% endif %} -{% if "function" in v %} - -{{ "Implementation: @ref %s." % v["function"] }} -{% endif %} -{% endif %} - diff --git a/doxygen/siphon_templates/default/index_entry.md b/doxygen/siphon_templates/default/index_entry.md deleted file mode 100644 index 479dcdb2..00000000 --- a/doxygen/siphon_templates/default/index_entry.md +++ /dev/null @@ -1,16 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -{{ "* [%s](@ref %s)" % (item["name"], meta["label"]) }} diff --git a/doxygen/siphon_templates/default/index_section.md b/doxygen/siphon_templates/default/index_section.md deleted file mode 100644 index 3c9d2b47..00000000 --- a/doxygen/siphon_templates/default/index_section.md +++ /dev/null @@ -1,18 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} - -@subpage {{ this.page_label(group) }} - diff --git a/doxygen/siphon_templates/default/item_format.md b/doxygen/siphon_templates/default/item_format.md deleted file mode 100644 index ed1b1bf7..00000000 --- a/doxygen/siphon_templates/default/item_format.md +++ /dev/null @@ -1,16 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -{{ raise NotImplementedError }} diff --git a/doxygen/siphon_templates/default/item_header.md b/doxygen/siphon_templates/default/item_header.md deleted file mode 100644 index 0c21e51f..00000000 --- a/doxygen/siphon_templates/default/item_header.md +++ /dev/null @@ -1,18 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} - -{{ "@page %s %s" % (this.page_label(group), this.page_title(group)) }} - diff --git a/doxygen/siphon_templates/itemlist/clicmd/item_format.itemlist b/doxygen/siphon_templates/itemlist/clicmd/item_format.itemlist new file mode 100644 index 00000000..195c3780 --- /dev/null +++ b/doxygen/siphon_templates/itemlist/clicmd/item_format.itemlist @@ -0,0 +1,17 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{# Just output the command path #} +{{ item['value']['path'] }} diff --git a/doxygen/siphon_templates/itemlist/default/index_entry.itemlist b/doxygen/siphon_templates/itemlist/default/index_entry.itemlist new file mode 100644 index 00000000..3b2494fb --- /dev/null +++ b/doxygen/siphon_templates/itemlist/default/index_entry.itemlist @@ -0,0 +1,15 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} diff --git a/doxygen/siphon_templates/itemlist/default/index_header.itemlist b/doxygen/siphon_templates/itemlist/default/index_header.itemlist new file mode 100644 index 00000000..3b2494fb --- /dev/null +++ b/doxygen/siphon_templates/itemlist/default/index_header.itemlist @@ -0,0 +1,15 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} diff --git a/doxygen/siphon_templates/itemlist/default/index_section.itemlist b/doxygen/siphon_templates/itemlist/default/index_section.itemlist new file mode 100644 index 00000000..3b2494fb --- /dev/null +++ b/doxygen/siphon_templates/itemlist/default/index_section.itemlist @@ -0,0 +1,15 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} diff --git a/doxygen/siphon_templates/itemlist/default/item_format.itemlist b/doxygen/siphon_templates/itemlist/default/item_format.itemlist new file mode 100644 index 00000000..ed1b1bf7 --- /dev/null +++ b/doxygen/siphon_templates/itemlist/default/item_format.itemlist @@ -0,0 +1,16 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{{ raise NotImplementedError }} diff --git a/doxygen/siphon_templates/itemlist/default/item_header.itemlist b/doxygen/siphon_templates/itemlist/default/item_header.itemlist new file mode 100644 index 00000000..3b2494fb --- /dev/null +++ b/doxygen/siphon_templates/itemlist/default/item_header.itemlist @@ -0,0 +1,15 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} diff --git a/doxygen/siphon_templates/itemlist/syscfg/item_format.itemlist b/doxygen/siphon_templates/itemlist/syscfg/item_format.itemlist new file mode 100644 index 00000000..02320519 --- /dev/null +++ b/doxygen/siphon_templates/itemlist/syscfg/item_format.itemlist @@ -0,0 +1,17 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{# Just output the item name #} +{{ item['name'] }} diff --git a/doxygen/siphon_templates/markdown/clicmd/index_entry.md b/doxygen/siphon_templates/markdown/clicmd/index_entry.md new file mode 100644 index 00000000..1fa9ec9b --- /dev/null +++ b/doxygen/siphon_templates/markdown/clicmd/index_entry.md @@ -0,0 +1,17 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{% set v = item['value'] %} +{{ "* [%s](@ref %s)" % (v['path'], meta["label"]) }} diff --git a/doxygen/siphon_templates/markdown/clicmd/index_header.md b/doxygen/siphon_templates/markdown/clicmd/index_header.md new file mode 100644 index 00000000..4167f4dc --- /dev/null +++ b/doxygen/siphon_templates/markdown/clicmd/index_header.md @@ -0,0 +1,130 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +# Debug CLI {{'{#'}}clicmd} + +The VPP network stack comes equipped with a set of commands that are useful +for debugging. + +The easiest way to access the CLI (with proper permissions) is to use the +vppctl command: + +``` +sudo vppctl +``` + +The CLI parser matches static keyword strings, eventually invoking an action +function. Unambiguous partial keyword matching always occurs. The action +functions consume input until satisfied or until they fail. This model makes +for easy coding, but does not guarantee useful "help" output. It's up to the +CLI command writer to add useful help strings. + +You can find the source code of CLI commands by searching for instances of the +@c VLIB_CLI_COMMAND macro in the code source files. + +Please help maintain and improve this document to make and keep these commands +clear and useful! + +@todo Document where to modify this CLI intro text. + + +## Debug and Telnet CLI + +The debug CLI is enabled with the unix interactive parameter or startup +configuration option. This causes VPP to start without daemonizing and +presents a command line interface on the terminal where it is run. + +The Telnet CLI is enabled with the `cli-listen localhost:5002` option which +will cause VPP to listen for TCP connections on the localhost address port +@c 5002. A Telnet client can then connect to this port (for example, `telnet +localhost 5002`) and will receive a command line prompt. + +This configuration will enable both mechanisms: + +``` +unix { + interactive + cli-listen localhost:5002 +} +``` + +The debug CLI can operate in line mode, which may be useful when running +inside an IDE like Emacs. This is enabled with the option +`unix cli-line-mode`. Several other options exist that alter how this +CLI works, see the @ref syscfg section for details. + +The CLI starts with a banner graphic (which can be disabled) and a prompt. The +prompt will typically read `vpp` for a release version of VPP and `DBGvpp#` +for a development version with debugging enabled, for example: + + _______ _ _ _____ ___ + __/ __/ _ \ (_)__ | | / / _ \/ _ \ + _/ _// // / / / _ \ | |/ / ___/ ___/ + /_/ /____(_)_/\___/ |___/_/ /_/ + + vpp# + +versus: + + _______ _ _ _____ ___ + __/ __/ _ \ (_)__ | | / / _ \/ _ \ + _/ _// // / / / _ \ | |/ / ___/ ___/ + /_/ /____(_)_/\___/ |___/_/ /_/ + + DBGvpp# + +This prompt can be configured with the `unix cli-prompt` setting and the +banner is disabled with `unix cli-no-banner`. + +## CLI features + +The CLI has several editing features that make it easy to use. + +- Cursor keys left/right will move the cursor within a command line; + typing will insert at the cursor; erase will erase at the cursor. + +- Ctrl-left/right will search for the start of the next word to + the left or right. +- Home/end will jump the cursor to the start and end of the line. +- Cursor keys up/down and ^P/^N iterate through the command history + buffer. Lines from the history buffer may be edited. New commands + are added to the end of the buffer when executed; though + duplicates of the previous command are not added. +- ^U erases the line contents from the left of the cursor to the + start. +- ^K erases the contents from the cursor to the end. +- ^S/^R will search the command history forwards or in reverse for + a command; start typing for matches to auto complete. +- ^L will clear the screen (if supported by the terminal) and repaint + the prompt and any current line. The cursor position is also + retained. +- The CLI can be closed with the quit command. Alternatively, ^D on + an empty input line will also close the session. Closing the debug + session will also shutdown VPP. + +Output that exceeds the length of a terminal page will be buffered, up to a +limit. + +- Space or page-down displays the next page. +- Enter or down-arrow displays the next line. +- Page-up goes back a page. +- Up-arrow goes up a line. +- Home/end jump to the start/end of the buffered output. +- The key q quits the pager. Space and enter will also quit the + pager if the end of the buffer has been reached. + +## Index of CLI commands + +[TOC] diff --git a/doxygen/siphon_templates/markdown/clicmd/item_format.md b/doxygen/siphon_templates/markdown/clicmd/item_format.md new file mode 100644 index 00000000..288dae40 --- /dev/null +++ b/doxygen/siphon_templates/markdown/clicmd/item_format.md @@ -0,0 +1,59 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{% set v = item['value'] %} +{{ "@section %s %s" % (meta['label'], v['path']) }} +{% if 'short_help' in v %} + +### Summary/usage + +{% set str = v['short_help'] %} +{% set period = "." if str[-1] != "." else "" %} +{% set prefix = " " if "[" in str or "<" in str or "|" in str else "" %} +{% set str = this.unescape(str) %} +{{ "%s%s%s" % (prefix, str, period) }} +{% endif %} +{% if 'long_help' in v %} +{# This is seldom used and will likely be deprecated #} + +### Long help + +{{ v['long_help'] }} +{% endif %} +{% if 'siphon_block' in item['meta'] %} +{% set sb = item["meta"]["siphon_block"] %} +{% if sb %} +{# Extracted from the code in /*? ... ?*/ blocks #} + +### Description + +{{ sb }} +{% endif %} +{% endif %} +{% if 'name' in meta or 'function' in v %} +{# Gives some developer-useful linking #} + +### Declaration and implementation +{% if "name" in meta %} + +{{ "Declaration: @ref %s (@ref %s line %d)" % + (meta['name'], meta["file"], item["meta"]["line_start"]) }} +{% endif %} +{% if "function" in v %} + +{{ "Implementation: @ref %s." % v["function"] }} +{% endif %} +{% endif %} + diff --git a/doxygen/siphon_templates/markdown/default/index_entry.md b/doxygen/siphon_templates/markdown/default/index_entry.md new file mode 100644 index 00000000..479dcdb2 --- /dev/null +++ b/doxygen/siphon_templates/markdown/default/index_entry.md @@ -0,0 +1,16 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{{ "* [%s](@ref %s)" % (item["name"], meta["label"]) }} diff --git a/doxygen/siphon_templates/markdown/default/index_section.md b/doxygen/siphon_templates/markdown/default/index_section.md new file mode 100644 index 00000000..3c9d2b47 --- /dev/null +++ b/doxygen/siphon_templates/markdown/default/index_section.md @@ -0,0 +1,18 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} + +@subpage {{ this.page_label(group) }} + diff --git a/doxygen/siphon_templates/markdown/default/item_format.md b/doxygen/siphon_templates/markdown/default/item_format.md new file mode 100644 index 00000000..ed1b1bf7 --- /dev/null +++ b/doxygen/siphon_templates/markdown/default/item_format.md @@ -0,0 +1,16 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{{ raise NotImplementedError }} diff --git a/doxygen/siphon_templates/markdown/default/item_header.md b/doxygen/siphon_templates/markdown/default/item_header.md new file mode 100644 index 00000000..0c21e51f --- /dev/null +++ b/doxygen/siphon_templates/markdown/default/item_header.md @@ -0,0 +1,18 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} + +{{ "@page %s %s" % (this.page_label(group), this.page_title(group)) }} + diff --git a/doxygen/siphon_templates/markdown/syscfg/index_header.md b/doxygen/siphon_templates/markdown/syscfg/index_header.md new file mode 100644 index 00000000..5d338a04 --- /dev/null +++ b/doxygen/siphon_templates/markdown/syscfg/index_header.md @@ -0,0 +1,111 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +# Startup Configuration {{'{#'}}syscfg} + +The VPP network stack comes with several configuration options that can be +provided either on the command line or in a configuration file. + +Specific applications built on the stack have been known to require a dozen +arguments, depending on requirements. This section describes commonly-used +options and parameters. + +You can find command-line argument parsers in the source code by searching for +instances of the `VLIB_CONFIG_FUNCTION` macro. The invocation +`VLIB_CONFIG_FUNCTION(foo_config, "foo")` will cause the function +`foo_config` to receive all the options and values supplied in a parameter +block named "`foo`", for example: `foo { arg1 arg2 arg3 ... }`. + +@todo Tell the nice people where this document lives so that the might +help improve it! + +## Command-line arguments + +Parameters are grouped by a section name. When providing more than one +parameter to a section all parameters for that section must be wrapped in +curly braces. + +``` +/usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 } +``` + +Which will produce output similar to this: + + + _______ _ _ _____ ___ + __/ __/ _ \ (_)__ | | / / _ \/ _ \ + _/ _// // / / / _ \ | |/ / ___/ ___/ + /_/ /____(_)_/\___/ |___/_/ /_/ + + vpp# + +When providing only one such parameter the braces are optional. For example, +the following command argument, `unix interactive` does not have braces: + +``` +/usr/bin/vpp unix interactive +``` + +The command line can be presented as a single string or as several; anything +given on the command line is concatenated with spaces into a single string +before parsing. + +VPP applications must be able to locate their own executable images. The +simplest way to ensure this will work is to invoke a VPP application by giving +its absolute path; for example: `/usr/bin/vpp `. At startup, VPP +applications parse through their own ELF-sections (primarily) to make lists +of init, configuration, and exit handlers. + +When developing with VPP, in _gdb_ it's often sufficient to start an application +like this at the `(gdb)` prompt: + +``` +run unix interactive +``` + +## Configuration file + +It is also possible to supply parameters in a startup configuration file the +path of which is provided to the VPP application on its command line. + +The format of the configuration file is a simple text file with the same +content as the command line but with the benefit of being able to use newlines +to make the content easier to read. For example: + +``` +unix { + nodaemon + log /tmp/vpp.log + full-coredump + cli-listen localhost:5002 +} +api-trace { + on +} +dpdk { + dev 0000:03:00.0 +} +``` + +VPP is then instructed to load this file with the `-c` option: + +``` +/usr/bin/vpp -c /etc/vpp/startup.conf +``` + +## Index of startup command sections + +[TOC] + diff --git a/doxygen/siphon_templates/markdown/syscfg/item_format.md b/doxygen/siphon_templates/markdown/syscfg/item_format.md new file mode 100644 index 00000000..53136115 --- /dev/null +++ b/doxygen/siphon_templates/markdown/syscfg/item_format.md @@ -0,0 +1,42 @@ +{# +# Copyright (c) 2016 Comcast Cable Communications Management, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#} +{% set v = item['value'] %} +{{ "@section %s %s" % (meta['label'], item['name']) }} +{% if 'siphon_block' in item['meta'] %} +{% set sb = item["meta"]["siphon_block"] %} +{% if sb %} +{# Extracted from the code in /*? ... ?*/ blocks #} + +### Description + +{{ sb }} +{% endif %} +{% endif %} +{% if "name" in meta or "function" in item %} +{# Gives some developer-useful linking #} + +### Declaration and implementation +{% if "name" in meta %} + +{{ "Declaration: @ref %s (@ref %s line %d)" % + (meta['name'], meta["file"], item["meta"]["line_start"]) }} +{% endif %} +{% if "function" in item %} + +{{ "Implementation: @ref %s." % item["function"] }} +{% endif %} +{% endif %} + diff --git a/doxygen/siphon_templates/syscfg/index_header.md b/doxygen/siphon_templates/syscfg/index_header.md deleted file mode 100644 index 5d338a04..00000000 --- a/doxygen/siphon_templates/syscfg/index_header.md +++ /dev/null @@ -1,111 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -# Startup Configuration {{'{#'}}syscfg} - -The VPP network stack comes with several configuration options that can be -provided either on the command line or in a configuration file. - -Specific applications built on the stack have been known to require a dozen -arguments, depending on requirements. This section describes commonly-used -options and parameters. - -You can find command-line argument parsers in the source code by searching for -instances of the `VLIB_CONFIG_FUNCTION` macro. The invocation -`VLIB_CONFIG_FUNCTION(foo_config, "foo")` will cause the function -`foo_config` to receive all the options and values supplied in a parameter -block named "`foo`", for example: `foo { arg1 arg2 arg3 ... }`. - -@todo Tell the nice people where this document lives so that the might -help improve it! - -## Command-line arguments - -Parameters are grouped by a section name. When providing more than one -parameter to a section all parameters for that section must be wrapped in -curly braces. - -``` -/usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 } -``` - -Which will produce output similar to this: - - - _______ _ _ _____ ___ - __/ __/ _ \ (_)__ | | / / _ \/ _ \ - _/ _// // / / / _ \ | |/ / ___/ ___/ - /_/ /____(_)_/\___/ |___/_/ /_/ - - vpp# - -When providing only one such parameter the braces are optional. For example, -the following command argument, `unix interactive` does not have braces: - -``` -/usr/bin/vpp unix interactive -``` - -The command line can be presented as a single string or as several; anything -given on the command line is concatenated with spaces into a single string -before parsing. - -VPP applications must be able to locate their own executable images. The -simplest way to ensure this will work is to invoke a VPP application by giving -its absolute path; for example: `/usr/bin/vpp `. At startup, VPP -applications parse through their own ELF-sections (primarily) to make lists -of init, configuration, and exit handlers. - -When developing with VPP, in _gdb_ it's often sufficient to start an application -like this at the `(gdb)` prompt: - -``` -run unix interactive -``` - -## Configuration file - -It is also possible to supply parameters in a startup configuration file the -path of which is provided to the VPP application on its command line. - -The format of the configuration file is a simple text file with the same -content as the command line but with the benefit of being able to use newlines -to make the content easier to read. For example: - -``` -unix { - nodaemon - log /tmp/vpp.log - full-coredump - cli-listen localhost:5002 -} -api-trace { - on -} -dpdk { - dev 0000:03:00.0 -} -``` - -VPP is then instructed to load this file with the `-c` option: - -``` -/usr/bin/vpp -c /etc/vpp/startup.conf -``` - -## Index of startup command sections - -[TOC] - diff --git a/doxygen/siphon_templates/syscfg/item_format.md b/doxygen/siphon_templates/syscfg/item_format.md deleted file mode 100644 index 53136115..00000000 --- a/doxygen/siphon_templates/syscfg/item_format.md +++ /dev/null @@ -1,42 +0,0 @@ -{# -# Copyright (c) 2016 Comcast Cable Communications Management, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at: -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#} -{% set v = item['value'] %} -{{ "@section %s %s" % (meta['label'], item['name']) }} -{% if 'siphon_block' in item['meta'] %} -{% set sb = item["meta"]["siphon_block"] %} -{% if sb %} -{# Extracted from the code in /*? ... ?*/ blocks #} - -### Description - -{{ sb }} -{% endif %} -{% endif %} -{% if "name" in meta or "function" in item %} -{# Gives some developer-useful linking #} - -### Declaration and implementation -{% if "name" in meta %} - -{{ "Declaration: @ref %s (@ref %s line %d)" % - (meta['name'], meta["file"], item["meta"]["line_start"]) }} -{% endif %} -{% if "function" in item %} - -{{ "Implementation: @ref %s." % item["function"] }} -{% endif %} -{% endif %} - -- cgit 1.2.3-korg