Skip to content

Commit 004d49e

Browse files
faraazbrcmfaraazbrcm
authored
Update details with respect to document generators and JSON tools
Updated details with respect to document generators and JSON tools
1 parent fcd8129 commit 004d49e

File tree

1 file changed

+239
-3
lines changed

1 file changed

+239
-3
lines changed

‎doc/mgmt/Developer Guide.md

+239-3
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
* [2.9.4 Preprocess XML files](#294-preprocess-xml-files)
6868
* [2.9.5 CLI directory structure](#295-cli-directory-structure)
6969
* [2.9.6 Generic REST Client](#296-generic-rest-client-for-actioner-scripts)
70+
* [2.9.7 Tool for JSON navigation in jinja templates](#297-tool-for-json-navigation-in-jinja-templates)
7071
* [2.10 REST Server](#210-rest-server)
7172
* [2.11 gNMI](#211-gnmi)
7273
* [2.12 Compilation](#212-compilation)
@@ -1324,7 +1325,11 @@ Actioner can be defined with the <ACTION> tag in the XML file.
13241325
test='${supported_breakout_modes} -ct ETHERNET:BREAKOUT_1x1:100GIGE'
13251326
/>
13261327
```
1327-
3. Write/Update Renderer scripts and templates. The JSON response from the swagger client API is received by the actioner and passes the response to the renderer script. The renderer script will invoke the jinja2 template with the JSON response. The template will parse the JSON response and generate the CLI output. Refer files in the below path for an example of usage
1328+
3. Write/Update Renderer scripts and templates.
1329+
The JSON response from the swagger client API is received by the actioner and passes the response to the renderer script.
1330+
The renderer script will invoke the jinja2 template with the JSON response. The template will parse the JSON response and generate the CLI output.
1331+
Please use [JSON tool](#297-tool-for-json-navigation-in-jinja-templates) to efficiently access the JSON data.
1332+
Refer files in the below path for an example of usage
13281333
13291334
**Renderer path**:
13301335
sonic-mgmt-framework/CLI/renderer
@@ -1621,6 +1626,75 @@ def my_new_error_message_formatter(status_code, error_entry):
16211626
return "Application error.. Please retry."
16221627
```
16231628
1629+
#### 2.9.7 Tool for JSON navigation in jinja templates
1630+
1631+
Developers can use this tool to retrieve the JSON data efficiently and check for the existence of nodes.
1632+
The tool uses the path in the GNMI style for querying and checking the nodes.
1633+
Following are the APIs exposed by the tool
1634+
1635+
#### get(json_data, path)
1636+
params
1637+
json_data: JSON data in the form of dictionary
1638+
path: The GNMI style path, examples below
1639+
return value
1640+
On success returns the queried nodes (format/type will be as present in JSON data)
1641+
on Failure returns None
1642+
1643+
##### Example:
1644+
1645+
```code
1646+
(Pdb) get(data, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/")
1647+
{'name': 'MyACL1', 'type': 'ACL_IPV4', 'description': 'Description for MyACL1'}
1648+
1649+
```
1650+
1651+
#### get_str(json_data, path)
1652+
params
1653+
json_data: JSON data in the form of dictionary
1654+
path: The GNMI style path, examples below
1655+
return value
1656+
On success returns the queried nodes (format/type will be strigified)
1657+
on Failure returns None
1658+
1659+
##### Example:
1660+
1661+
```code
1662+
(Pdb) get_str(data, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/")
1663+
"{'name': 'MyACL1', 'type': 'ACL_IPV4', 'description': 'Description for MyACL1'}"
1664+
1665+
```
1666+
1667+
#### contains(json_data, path)
1668+
params
1669+
json_data: JSON data in the form of dictionary
1670+
path: The GNMI style path, examples below
1671+
return value
1672+
On success returns True
1673+
on Failure returns False
1674+
1675+
##### Example:
1676+
1677+
```code
1678+
(Pdb) contains(data, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/")
1679+
True
1680+
(Pdb) contains(data, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/not_present")
1681+
False
1682+
1683+
```
1684+
1685+
#### Sample usage in the renderer
1686+
1687+
```text
1688+
{{json_tools.get(json_output, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]")}}
1689+
{{json_tools.get(json_output, "/acl-sets/acl-set[name=MyACL1]")}}
1690+
{{json_tools.get(json_output, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/type")}}
1691+
{{json_tools.get_str(json_output, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/type")}}
1692+
{{json_tools.contains(json_output, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/type_not")}}
1693+
{{json_tools.contains(json_output, "/acl-sets/acl-set[name=MyACL1][type=ACL_IPV4]/config/type")}}
1694+
1695+
```
1696+
1697+
16241698
### 2.10 REST Server
16251699
16261700
sonic-mgmt-framework repository contains REST Server infrastructure code.
@@ -1907,8 +1981,170 @@ It is automatically run along with [Swagger Server Generator](#315-swagger-serve
19071981
19081982
#### 3.1.8 RESTCONF Documentation Generator
19091983
1910-
TODO
1984+
RESTCONF documentation is generated automatically as part of build during the phase when OpenAPIs(YAML) for YANG modules are generated.
1985+
No extra step is needed from developers. RESTCONF document generator is a submodule in OpenAPI Generator and it relies on YANG's description
1986+
statements for documentation text.
1987+
1988+
Developers are requested to have a description statements in YANG models for all Data nodes such as container/list/leaf/leaf-list/rpc.
1989+
For any data node which does not have description statement, the generated document will have blank text i.e. empty sections
1990+
1991+
The generated document will be in a github complaint markdown format (.md)
1992+
The document will be generated for each top level YANG module in normalized tree. For more information on how generator works please refer [section 3.1.4](#314-OpenAPI-Generator)
1993+
1994+
The generated documents will be written to `sonic-mgmt-framework/build/restconf_md` directory.
19111995
19121996
#### 3.1.9 CLI Documentation Generator
19131997
1914-
TODO
1998+
CLI Document generator tool will generate the documentation using KLISH CLI model XMLs.
1999+
Command name, mode, syntax and parameter description are already available in model XML.
2000+
Additional tags will be introduced for developers to specify command description, usage info and examples for each COMMAND.
2001+
2002+
- DOCGEN tag to group all document generation related tags - it can include one DESCRIPTION, one USAGE and one or more EXAMPLE, ALTCMD and FEATURE tags.
2003+
- DESCRIPTION tag to provide a detailed description of the command.
2004+
- USAGE tag to specify usage guidelines - when to use, preconditions, suggested next actions, etc.
2005+
- EXAMPLE tags to specify examples and sample output.
2006+
- ALTCMD tags to specify alternative commands in other CLI framework such as VTYSH, CLICK and in fact other alternate commands in KLISH itself (if available).
2007+
2008+
All these documentation tags will be optional. They are used only for document generation and not to render the commands.
2009+
2010+
Document generator tool will consume all model XMLs from src/CLI/clitree/cli-xml directory to generate CLI document in markdown syntax.
2011+
Below table summarizes how each section of document template will be derived from above defined XML tags.
2012+
2013+
```text
2014+
+----------------+-----------------+-------------------+---------------------------------------------------------------------------+
2015+
| Section. | XML TAG | Attribute | Comments |
2016+
+----------------+-----------------+-------------------+---------------------------------------------------------------------------+
2017+
| Command name | COMMAND | | |
2018+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------+
2019+
| Description | DESCRIPTION | | Use “help” value of COMMAND tag if DESCRIPTION tag is not specified. |
2020+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2021+
| Syntax | PARAM | name | Lists all possible combinations of parameters |
2022+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2023+
| Parameters | PARAM | name, help, ptype | |
2024+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2025+
| Modes | VIEW | name | Parent command name will be shown here. The VIEW “name” attribute provides|
2026+
| | | | internal name of the mode. Tool will lookup the parent command by matching|
2027+
| | | | the VIEW “name” value with other COMMAND tag’s “view” attribute value |
2028+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2029+
| Usage | | | |
2030+
| guidelines | USAGE | | Will be skipped if developer did not specify USAGE tag |
2031+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2032+
| Examples | EXAMPLE | | Will be skipped if developer did not specify EXAMPLE tags |
2033+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2034+
| Features | FEATURE | | Will be skipped if developer did not specify FEATURE tags |
2035+
|----------------|-----------------|-------------------|---------------------------------------------------------------------------|
2036+
| ALTCMDS | ALTCMD | type | Will be skipped if developer did not specify ALTCMD tags |
2037+
+----------------+-----------------|-------------------|---------------------------------------------------------------------------|
2038+
2039+
```
2040+
CLI document generator is automatically run during sonic-mgmt-framework compilation.
2041+
It can be manually trigged through following commands:
2042+
2043+
```bash
2044+
cd /sonic/sonic-buildimage/src/sonic-mgmt-framework
2045+
make clidocgen (to generate the document)
2046+
make clidocgen-clean (to clean the document)
2047+
```
2048+
The document will be written to `sonic-mgmt-framework/build/cli/command-tree/industry_standard_cli_reference_guide.md` directory.
2049+
2050+
#### 3.1.9.1 Sample CLI Model
2051+
2052+
```text
2053+
2054+
<VIEW name="view-name">
2055+
2056+
<COMMAND
2057+
name="command-tokens"
2058+
help="CLI help string"
2059+
>
2060+
<PARAM
2061+
name="param1"
2062+
help="Help string for param1"
2063+
ptype="UINT"
2064+
/>
2065+
<PARAM
2066+
name="param2"
2067+
help="Help string for param2"
2068+
ptype="STRING"
2069+
/>
2070+
<ACTION>...</ACTION>
2071+
<DOCGEN>
2072+
<DESCRIPTION>
2073+
Detailed command description
2074+
</DESCRIPTION>
2075+
<USAGE>
2076+
Usage information
2077+
</USAGE>
2078+
<EXAMPLE summary="Example1 description">
2079+
Example1 body
2080+
</EXAMPLE>
2081+
<EXAMPLE summary="Example2 description">
2082+
Example2 body
2083+
</EXAMPLE>
2084+
2085+
<FEATURE> ZTP </FEATURE>
2086+
<FEATURE> ZTP-cli </FEATURE>
2087+
<ALTCMD type="click">
2088+
config ztp -y enable
2089+
</ALTCMD>
2090+
<ALTCMD type="vtysh">
2091+
....
2092+
</ALTCMD>
2093+
2094+
</DOCGEN>
2095+
</COMMAND>
2096+
2097+
</VIEW>
2098+
2099+
```
2100+
2101+
#### 3.1.9.2 Sample Generated Document
2102+
2103+
```text
2104+
### command-tokens
2105+
2106+
Detailed command description
2107+
2108+
#### Syntax
2109+
2110+
command-tokens param1
2111+
command-tokens param2
2112+
2113+
#### Parameters
2114+
2115+
Name | Description | Data type
2116+
-------|------------------------|--------
2117+
Param1 | Help string for param1 | UINT
2118+
Param2 | Help string for param2 | STRING
2119+
2120+
#### Mode
2121+
2122+
Parent command - derived from view-name
2123+
2124+
#### Usage Guidelines
2125+
2126+
Usage information
2127+
2128+
#### Examples
2129+
2130+
Example1 description
2131+
2132+
Example1 body
2133+
2134+
Example2 description
2135+
2136+
Example2 body
2137+
2138+
### Alternate Commands
2139+
2140+
#### click
2141+
config ztp -y enable
2142+
2143+
#### vtysh
2144+
...
2145+
2146+
### Features this CLI belongs to
2147+
* ZTP
2148+
* ZTP-cli
2149+
2150+
```

0 commit comments

Comments
 (0)