[net-next,v2] docs: netlink: link to family documentations from spec info

Commit Message

Jakub Kicinski Nov. 29, 2023, 4:14 a.m. UTC

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 <[e-mail]>
Reviewed-by: Donald Hunter <[e-mail]>
Signed-off-by: Jakub Kicinski <[e-mail]>
---
v2:
 - add type to the arg
 - link from index
v1: https://lore.kernel.org/all/[e-mail]/

CC: [e-mail]
CC: [e-mail]
---
 Documentation/userspace-api/netlink/index.rst | 4 +++-
 Documentation/userspace-api/netlink/specs.rst | 2 +-
 tools/net/ynl/ynl-gen-rst.py                  | 8 +++++++-
 3 files changed, 11 insertions(+), 3 deletions(-)

Comments

Jiri Pirko Nov. 29, 2023, 2:47 p.m. UTC | #1

Wed, Nov 29, 2023 at 05:14:27AM CET, [e-mail] wrote:
>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 <[e-mail]>
>Reviewed-by: Donald Hunter <[e-mail]>
>Signed-off-by: Jakub Kicinski <[e-mail]>

Reviewed-by: Jiri Pirko <[e-mail]>

[e-mail] Dec. 1, 2023, 7:20 a.m. UTC | #2

Hello:

This patch was applied to netdev/net-next.git (main)
by Jakub Kicinski <[e-mail]>:

On Tue, 28 Nov 2023 20:14:27 -0800 you wrote:
> 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 <[e-mail]>
> Reviewed-by: Donald Hunter <[e-mail]>
> Signed-off-by: Jakub Kicinski <[e-mail]>
> 
> [...]

Here is the summary with links:
  - [net-next,v2] docs: netlink: link to family documentations from spec info
    https://git.kernel.org/netdev/net-next/c/e8c780a57060

You are awesome, thank you!

Patch

diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst
index 62725dafbbdb..c1b6765cc963 100644
--- a/Documentation/userspace-api/netlink/index.rst
+++ b/Documentation/userspace-api/netlink/index.rst
@@ -16,4 +16,6 @@  Netlink documentation for users.
    genetlink-legacy
    netlink-raw
 
-See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`.
+See also:
+ - :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`
+ - :ref:`Documentation/networking/netlink_spec/index.rst <specs>`
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 tables
 
diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py
index b6292109e236..8c62e040df5d 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) -> 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)