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

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

[Jakub Kicinski]

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.

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

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

[kernel test robot]

Hi Jakub,

kernel test robot noticed the following build warnings:

[auto build test WARNING on net-next/main]

url:    https://github.com/intel-lab-lkp/linux/commits/Jakub-Kicinski/docs-netlink-link-to-family-documentations-from-spec-info/20231128-050136
base:   net-next/main
patch link:    https://lore.kernel.org/r/20231127205642.2293153-1-kuba%40kernel.org
patch subject: [PATCH net-next] docs: netlink: link to family documentations from spec info
reproduce: (https://download.01.org/0day-ci/archive/20231128/202311280834.lYzXIFc4-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202311280834.lYzXIFc4-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[Jakub Kicinski]

On Tue, 28 Nov 2023 11:01:55 +0800 kernel test robot wrote:
> Hi Jakub,
> 
> kernel test robot noticed the following build warnings:
> 
> [auto build test WARNING on net-next/main]
> 
> url:    https://github.com/intel-lab-lkp/linux/commits/Jakub-Kicinski/docs-netlink-link-to-family-documentations-from-spec-info/20231128-050136
> base:   net-next/main
> patch link:    https://lore.kernel.org/r/20231127205642.2293153-1-kuba%40kernel.org
> patch subject: [PATCH net-next] docs: netlink: link to family documentations from spec info
> reproduce: (https://download.01.org/0day-ci/archive/20231128/202311280834.lYzXIFc4-lkp@intel.com/reproduce)
> 
> If you fix the issue in a separate patch/commit (i.e. not just a new version of
> the same patch/commit), kindly add following tags
> | Reported-by: kernel test robot <lkp@intel.com>
> | Closes: https://lore.kernel.org/oe-kbuild-all/202311280834.lYzXIFc4-lkp@intel.com/
> 
> All warnings (new ones prefixed by >>):
> 
> >> Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst  

Is it possible that the build bot is missing python-yaml support and
the generation of Documentation/networking/netlink_spec/index.rst
fails?

Or is this an ordering issue?

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

[Yujie Liu]

On Mon, Nov 27, 2023 at 07:06:11PM -0800, Jakub Kicinski wrote:
> On Tue, 28 Nov 2023 11:01:55 +0800 kernel test robot wrote:
> > Hi Jakub,
> > 
> > kernel test robot noticed the following build warnings:
> > 
> > [auto build test WARNING on net-next/main]
> > 
> > url:    https://github.com/intel-lab-lkp/linux/commits/Jakub-Kicinski/docs-netlink-link-to-family-documentations-from-spec-info/20231128-050136
> > base:   net-next/main
> > patch link:    https://lore.kernel.org/r/20231127205642.2293153-1-kuba%40kernel.org
> > patch subject: [PATCH net-next] docs: netlink: link to family documentations from spec info
> > reproduce: (https://download.01.org/0day-ci/archive/20231128/202311280834.lYzXIFc4-lkp@intel.com/reproduce)
> > 
> > If you fix the issue in a separate patch/commit (i.e. not just a new version of
> > the same patch/commit), kindly add following tags
> > | Reported-by: kernel test robot <lkp@intel.com>
> > | Closes: https://lore.kernel.org/oe-kbuild-all/202311280834.lYzXIFc4-lkp@intel.com/
> > 
> > All warnings (new ones prefixed by >>):
> > 
> > >> Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst  
> 
> Is it possible that the build bot is missing python-yaml support and
> the generation of Documentation/networking/netlink_spec/index.rst
> fails?

Hi Jakub, this is indeed due to missing pyyaml module in the bot so the
doc file is not generated. We've installed it now and the warning is
gone. Sorry for the noise and please ignore this report.

> 
> Or is this an ordering issue?
> 

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

[Jakub Kicinski]

On Thu, 30 Nov 2023 16:52:10 +0800 Yujie Liu wrote:
> > Is it possible that the build bot is missing python-yaml support and
> > the generation of Documentation/networking/netlink_spec/index.rst
> > fails?  
> 
> Hi Jakub, this is indeed due to missing pyyaml module in the bot so the
> doc file is not generated. We've installed it now and the warning is
> gone. Sorry for the noise and please ignore this report.

No worries at all, thanks for confirming!

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

[Breno Leitao]

On Mon, Nov 27, 2023 at 12:56:42PM -0800, Jakub Kicinski wrote:

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

Please add the type hinting to the "title" argument. Something as:

  def rst_label(title: str) -> str:

Other than that I am good, and feel free to add:

Reviewed-by: Breno Leitao <leitao@debian.org>

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

[Donald Hunter]

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)