Re: [PATCH net-next] docs: netlink: link to family documentations from spec info
From: Donald Hunter <donald.hunter@gmail.com>
Date: 2023-11-28 10:21:48
Also in:
linux-doc
Jakub Kicinski [off-list ref] writes:
To increase the chances of people finding the rendered docs add a link to specs.rst. Add a label in the generated index.rst and while at it adjust the title a little bit.
It might be useful to also link to the rendered docs directly from the "Netlink Handbook" at Documentation/userspace-api/netlink/index.rst? Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
quoted hunk
Signed-off-by: Jakub Kicinski <kuba@kernel.org> --- CC: corbet@lwn.net CC: leitao@debian.org CC: linux-doc@vger.kernel.org --- Documentation/userspace-api/netlink/specs.rst | 2 +- tools/net/ynl/ynl-gen-rst.py | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-)diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index c1b951649113..1b50d97d8d7c 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst@@ -15,7 +15,7 @@ kernel headers directly. Internally kernel uses the YAML specs to generate: - the C uAPI header - - documentation of the protocol as a ReST file + - documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>` - policy tables for input attribute validation - operation tablesdiff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py index b6292109e236..2c0b80071bcd 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py@@ -122,6 +122,11 @@ SPACE_PER_LEVEL = 4 return "\n".join(lines) +def rst_label(title) -> str: + """Return a formatted label""" + return f".. _{title}:\n\n" + + # Parsers # =======@@ -349,7 +354,8 @@ SPACE_PER_LEVEL = 4 lines = [] lines.append(rst_header()) - lines.append(rst_title("Netlink Specification")) + lines.append(rst_label("specs")) + lines.append(rst_title("Netlink Family Specifications")) lines.append(rst_toctree(1)) index_dir = os.path.dirname(output)