netdev - Re: [PATCH net-next] docs: netlink: link to family documentations from spec info

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <m2leai89g5.fsf@gmail.com>
Date: Tue, 28 Nov 2023 10:21:30 +0000
From: Donald Hunter <donald.hunter@...il.com>
To: Jakub Kicinski <kuba@...nel.org>
Cc: davem@...emloft.net,  netdev@...r.kernel.org,  edumazet@...gle.com,
  pabeni@...hat.com,  corbet@....net,  leitao@...ian.org,
  linux-doc@...r.kernel.org
Subject: Re: [PATCH net-next] docs: netlink: link to family documentations
 from spec info

Jakub Kicinski <kuba@...nel.org> 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@...il.com>

> Signed-off-by: Jakub Kicinski <kuba@...nel.org>
> ---
> CC: corbet@....net
> CC: leitao@...ian.org
> CC: linux-doc@...r.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 tables
>  
> diff --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)