Re: [PATCH v2 11/12] docs: use parser_yaml extension to handle Netlink specs

Donald Hunter
2025-06-13T11:55:48Z

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Instead of manually calling ynl_gen_rst.py, use a Sphinx extension.
> This way, no .rst files would be written to the Kernel source
> directories.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> Documentation/Makefile | 17 ---------
> Documentation/conf.py | 11 +++---
> Documentation/netlink/specs/index.rst | 38 +++++++++++++++++++
> Documentation/networking/index.rst | 2 +-
> .../networking/netlink_spec/readme.txt | 4 --
> Documentation/sphinx/parser_yaml.py | 2 +-
> 6 files changed, 46 insertions(+), 28 deletions(-)
> create mode 100644 Documentation/netlink/specs/index.rst
> delete mode 100644 Documentation/networking/netlink_spec/readme.txt
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index d30d66ddf1ad..9185680b1e86 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -102,22 +102,6 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
> cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
> fi
>
> -YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst
> -YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec
> -YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs
> -YNL_TOOL:=$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py
> -
> -YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
> -YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))
> -
> -$(YNL_INDEX): $(YNL_RST_FILES)
> - $(Q)$(YNL_TOOL) -o $@ -x
> -
> -$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
> - $(Q)$(YNL_TOOL) -i $< -o $@
> -
> -htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX)
> -
> htmldocs:
> @$(srctree)/scripts/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
> @@ -184,7 +168,6 @@ refcheckdocs:
> $(Q)cd $(srctree);scripts/documentation-file-ref-check
>
> cleandocs:
> - $(Q)rm -f $(YNL_INDEX) $(YNL_RST_FILES)
> $(Q)rm -rf $(BUILDDIR)
> $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 12de52a2b17e..add6ce78dd80 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -45,7 +45,7 @@ needs_sphinx = '3.4.3'
> extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
> 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
> 'maintainers_include', 'sphinx.ext.autosectionlabel',
> - 'kernel_abi', 'kernel_feat', 'translations']
> + 'kernel_abi', 'kernel_feat', 'translations', 'parser_yaml']
>
> # Since Sphinx version 3, the C function parser is more pedantic with regards
> # to type checking. Due to that, having macros at c:function cause problems.
> @@ -143,10 +143,11 @@ else:
> # Add any paths that contain templates here, relative to this directory.
> templates_path = ['sphinx/templates']
>
> -# The suffix(es) of source filenames.
> -# You can specify multiple suffix as a list of string:
> -# source_suffix = ['.rst', '.md']
> -source_suffix = '.rst'
> +# The suffixes of source filenames that will be automatically parsed
> +source_suffix = {
> + '.rst': 'restructuredtext',
> + '.yaml': 'yaml',

The handler name should probably be netlink_yaml

> +}
>
> # The encoding of source files.
> #source_encoding = 'utf-8-sig'
> diff --git a/Documentation/netlink/specs/index.rst b/Documentation/netlink/specs/index.rst
> new file mode 100644
> index 000000000000..ca0bf816dc3f
> --- /dev/null
> +++ b/Documentation/netlink/specs/index.rst
> @@ -0,0 +1,38 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. NOTE: This document was auto-generated.
> +
> +.. _specs:
> +
> +=============================
> +Netlink Family Specifications
> +=============================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + conntrack
> + devlink
> + dpll
> + ethtool
> + fou
> + handshake
> + lockd
> + mptcp_pm
> + net_shaper
> + netdev
> + nfsd
> + nftables
> + nl80211
> + nlctrl
> + ovpn
> + ovs_datapath
> + ovs_flow
> + ovs_vport
> + rt-addr
> + rt-link
> + rt-neigh
> + rt-route
> + rt-rule
> + tc
> + tcp_metrics
> + team
> diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
> index ac90b82f3ce9..b7a4969e9bc9 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -57,7 +57,7 @@ Contents:
> filter
> generic-hdlc
> generic_netlink
> - netlink_spec/index
> + ../netlink/specs/index
> gen_stats
> gtp
> ila
> diff --git a/Documentation/networking/netlink_spec/readme.txt b/Documentation/networking/netlink_spec/readme.txt
> deleted file mode 100644
> index 030b44aca4e6..000000000000
> --- a/Documentation/networking/netlink_spec/readme.txt
> +++ /dev/null
> @@ -1,4 +0,0 @@
> -SPDX-License-Identifier: GPL-2.0
> -
> -This file is populated during the build of the documentation (htmldocs) by the
> -tools/net/ynl/pyynl/ynl_gen_rst.py script.
> diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
> index eb32e3249274..cdcafe5b3937 100755
> --- a/Documentation/sphinx/parser_yaml.py
> +++ b/Documentation/sphinx/parser_yaml.py
> @@ -55,7 +55,7 @@ class YamlParser(Parser):
> fname = document.current_source
>
> # Handle netlink yaml specs
> - if re.search("/netlink/specs/", fname):
> + if re.search("netlink/specs/", fname):

Please combine this change into the earlier patch so that the series
doesn't have unnecessary changes.

> if fname.endswith("index.yaml"):
> msg = self.netlink_parser.generate_main_index_rst(fname, None)