T6342: extend schema to handle documentation in the xml interface definition

Author: rebortg

schema/interface_definition.rnc

@@ -97,6 +97,18 @@ properties = element properties
     valueHelp* &
     (element constraintErrorMessage { text })? &
     completionHelp* &
+    
+    # "docs" is used to store documentation for a node in a structured format
+    # It is used to generate documentation for the CLI and Web docs
+    (element docs {
+        (element headline { text })? &
+        (element text { text })? &
+        (element usageExample { text })? &
+        (element hints {
+            attribute type { text },
+            text
+        })*
+    })? &
 
     # These are meaningful only for leaf nodes
     (element valueless { empty })? &

schema/interface_definition.rng

@@ -2,19 +2,19 @@
 <grammar xmlns="http://relaxng.org/ns/structure/1.0">
   <!--
        interface_definition.rnc: VyConf reference tree XML grammar
-
+    
        Copyright (C) 2014. 2017 VyOS maintainers and contributors <maintainers@vyos.net>
-
+    
        This library is free software; you can redistribute it and/or
        modify it under the terms of the GNU Lesser General Public
        License as published by the Free Software Foundation; either
        version 2.1 of the License, or (at your option) any later version.
-
+    
        This library is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        Lesser General Public License for more details.
-
+    
        You should have received a copy of the GNU Lesser General Public
        License along with this library; if not, write to the Free Software
        Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
@@ -142,15 +142,15 @@
     Nodes may have properties
     For simplicity, any property is allowed in any node,
     but whether they are used or not is implementation-defined
-
+    
     Leaf nodes may differ in number of values that can be
     associated with them.
     By default, a leaf node can have only one value.
     "multi" tag means a node can have one or more values,
     "valueless" means it can have no values at all.
     "hidden" means node visibility can be toggled, eg 'dangerous' commands,
     "secret" allows a node to hide its value from unprivileged users.
-
+    
     "priority" is used to influence node processing order for nodes
     with exact same dependencies and in compatibility modes.
   -->
@@ -177,6 +177,39 @@
         <zeroOrMore>
           <ref name="completionHelp"/>
         </zeroOrMore>
+        <optional>
+          <!--
+            "docs" is used to store documentation for a node in a structured format
+            It is used to generate documentation for the CLI and Web docs
+          -->
+          <group>
+            <element name="docs">
+              <interleave>
+                <optional>
+                  <element name="headline">
+                    <text/>
+                  </element>
+                </optional>
+                <optional>
+                  <element name="text">
+                    <text/>
+                  </element>
+                </optional>
+                <optional>
+                  <element name="usageExample">
+                    <text/>
+                  </element>
+                </optional>
+                <zeroOrMore>
+                  <element name="hints">
+                    <attribute name="type"/>
+                    <text/>
+                  </element>
+                </zeroOrMore>
+              </interleave>
+            </element>
+          </group>
+        </optional>
         <optional>
           <!-- These are meaningful only for leaf nodes -->
           <group>