Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

T6342: extend schema to handle documentation in xml #4292

Open
wants to merge 1 commit into
base: current
Choose a base branch
from
Open

T6342: extend schema to handle documentation in xml #4292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions schema/interface_definition.rnc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 })? &
Expand Down
45 changes: 39 additions & 6 deletions schema/interface_definition.rng
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!--
interface_definition.rnc: VyConf reference tree XML grammar

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please clean the stray whitespaces?

Copy link
Member Author

@rebortg rebortg Jan 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can fix it, but this is the generated output from the interface_definition.rnc file with:
trang interface_definition.rnc interface_definition.rng

how should i deal with it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that we have a docker container and people don't have to install trang on their own machines, I wonder if we should even commit .rng files at all, or just generate them at build time. In any case, I think stray whitespace in autogenerated files is not an issue.

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
Expand Down Expand Up @@ -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.
-->
Expand All @@ -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>
Expand Down
Loading