Jakub Kicinski <kuba@xxxxxxxxxx> 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@xxxxxxxxx>
> Signed-off-by: Jakub Kicinski <kuba@xxxxxxxxxx>
> ---
> CC: corbet@xxxxxxx
> CC: leitao@xxxxxxxxxx
> CC: linux-doc@xxxxxxxxxxxxxxx
> ---
> 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)
