| Message ID | 20231127205642.2293153-1-kuba@kernel.org (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next] docs: netlink: link to family documentations from spec info | expand |
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
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?
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>
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)
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? >
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!
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)
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(-)