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

[Donald Hunter <donald.hunter@gmail.com>]

Jakub Kicinski <kuba@kernel.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@gmail.com>

> 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 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)