JIRA: https://issues.redhat.com/browse/RHEL-57756
Upstream commit(s):
commit cb7351ac17862cf8d4e00831ce4aa27f53bda01c
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Tue May 28 15:06:51 2024 +0100
doc: netlink: Fix formatting of op flags in generated .rst
Generate op flags as an inline list instead of a stringified python
value.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20240528140652.9445-4-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-57756
Upstream commit(s):
commit ebf9004136c76b7b62fe628a4bc88b3e894b4b95
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Tue May 28 15:06:50 2024 +0100
doc: netlink: Don't 'sanitize' op docstrings in generated .rst
The doc strings for do/dump ops are emitted as toplevel .rst constructs
so they can be multi-line. Pass multi-line text straight through to the
.rst to retain any simple formatting from the .yaml
This fixes e.g. list formatting for the pin-get docs in dpll.yaml:
https://docs.kernel.org/6.9/networking/netlink_spec/dpll.html#pin-get
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20240528140652.9445-3-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-57756
Upstream commit(s):
commit 8c1b74a26d96705ac55a43afe7a41fc6e44be390
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Fri Mar 29 13:50:20 2024 +0000
doc: netlink: Add hyperlinks to generated Netlink docs
Update ynl-gen-rst to generate hyperlinks to definitions, attribute
sets and sub-messages from all the places that reference them.
Note that there is a single label namespace for all of the kernel docs.
Hyperlinks within a single netlink doc need to be qualified by the
family name to avoid collisions.
The label format is 'family-type-name' which gives, for example,
'rt-link-attribute-set-link-attrs' as the link id.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20240329135021.52534-3-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-57756
Upstream commit(s):
commit 4cc1730a90fcdeac14eb44857b566a96e1170f79
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Fri Mar 29 13:50:19 2024 +0000
doc: netlink: Change generated docs to limit TOC to depth 3
The tables of contents in the generated Netlink docs include individual
attribute definitions. This can make the contents exceedingly long and
repeats a lot of what is on the rest of the pages. See for example:
https://docs.kernel.org/networking/netlink_spec/tc.html
Add a depth limit to the contents directive in generated .rst files to
limit the contents depth to 3 levels. This reduces the contents to:
- Family
- Summary
- Operations
- op-one
- op-two
- ...
- Definitions
- struct-one
- struct-two
- enum-one
- ...
- Attribute sets
- attrs-one
- attrs-two
- ...
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Breno Leitao <leitao@debian.org>
Link: https://lore.kernel.org/r/20240329135021.52534-2-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-57755
Upstream commit(s):
commit fe09ae5fb93be371a72d1b2ac62fb3eead51a728
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Mon Jan 29 22:34:57 2024 +0000
tools/net/ynl: Add type info to struct members in generated docs
Extend the ynl doc generator to include type information for struct
members, ignoring the pad type.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Jiri Pirko <jiri@nvidia.com>
Link: https://lore.kernel.org/r/20240129223458.52046-13-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-30145
Upstream commit(s):
commit 9b0aa2244d9d12cc39726ffabc0609a029fda95c
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Fri Dec 15 09:37:20 2023 +0000
tools/net/ynl-gen-rst: Remove extra indentation from generated docs
The output from ynl-gen-rst.py has extra indentation that causes extra
<blockquote> elements to be generated in the HTML output.
Reduce the indentation so that sphinx doesn't generate unnecessary
<blockquote> elements.
Reviewed-by: Breno Leitao <leitao@debian.org>
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-14-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-30145
Upstream commit(s):
commit e9d7c59212e43f079dffaf65001b006da6a12580
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Fri Dec 15 09:37:19 2023 +0000
tools/net/ynl-gen-rst: Remove bold from attribute-set headings
The generated .rst for attribute-sets currently uses a sub-sub-heading
for each attribute, with the attribute name in bold. This makes
attributes stand out more than the attribute-set sub-headings they are
part of.
Remove the bold markup from attribute sub-sub-headings.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-13-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-30145
Upstream commit(s):
commit e8c32339cf49cd9c2626e143c548f5897aa58b17
Author: Donald Hunter <donald.hunter@gmail.com>
Date: Fri Dec 15 09:37:18 2023 +0000
tools/net/ynl-gen-rst: Sort the index of generated netlink specs
The index of netlink specs was being generated unsorted. Sort the output
before generating the index entries.
Reviewed-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Breno Leitao <leitao@debian.org>
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Link: https://lore.kernel.org/r/20231215093720.18774-12-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-30145
Upstream commit(s):
commit e8c780a5706066eba210e4c514968d95ba29e052
Author: Jakub Kicinski <kuba@kernel.org>
Date: Tue Nov 28 20:14:27 2023 -0800
docs: netlink: link to family documentations from spec info
To increase the chances of people finding the rendered docs
add a link to specs.rst and index.rst.
Add a label in the generated index.rst and while at it adjust
the title a little bit.
Reviewed-by: Breno Leitao <leitao@debian.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Jiri Pirko <jiri@nvidia.com>
Link: https://lore.kernel.org/r/20231129041427.2763074-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Petr Oros <poros@redhat.com>
JIRA: https://issues.redhat.com/browse/RHEL-30145
Upstream commit(s):
commit f061c9f7d058ffc32de66f2efb3e1c368e305423
Author: Breno Leitao <leitao@debian.org>
Date: Tue Nov 21 03:48:31 2023 -0800
Documentation: Document each netlink family
This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> Netlink Specification documentation page.
Create a python script that is invoked during 'make htmldocs', reads the
YAML specs input file and generate the correspondent RST file.
Create a new Documentation/networking/netlink_spec index page, and
reference each Netlink RST file that was processed above in this main
index.rst file.
In case of any exception during the parsing, dump the error and skip
the file.
Do not regenerate the RST files if the input files (YAML) were not
changed in-between invocations.
Suggested-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Breno Leitao <leitao@debian.org>
----
Changelog:
V3:
* Do not regenerate the RST files if the input files were not
changed. In order to do it, a few things changed:
- Rely on Makefile more to find what changed, and trigger
individual file processing
- The script parses file by file now (instead of batches)
- Create a new option to generate the index file
V2:
* Moved the logic from a sphinx extension to a external script
* Adjust some formatting as suggested by Donald Hunter and Jakub
* Auto generating all the rsts instead of having stubs
* Handling error gracefully
Reviewed-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Signed-off-by: Petr Oros <poros@redhat.com>
Petr Oros