Commit 1ce4da3d authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: use parser_yaml extension to handle Netlink specs 



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.

We are using here a toctree with :glob: property. This way, there
is no need to touch the netlink/specs/index.rst file every time
a new Netlink spec is added/renamed/removed.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: default avatarDonald Hunter <donald.hunter@gmail.com>
parent bb1e3629

Documentation/Makefile

+0 −17
Original line number Diff line number Diff line
@@ -104,22 +104,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)))
@@ -186,7 +170,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

Documentation/conf.py

+15 −5
Original line number Diff line number Diff line
@@ -42,6 +42,15 @@ exclude_patterns = [] 
dyn_include_patterns = []

dyn_exclude_patterns = ["output"]



# Currently, only netlink/specs has a parser for yaml.

# Prefer using include patterns if available, as it is faster

if has_include_patterns:

    dyn_include_patterns.append("netlink/specs/*.yaml")

else:

    dyn_exclude_patterns.append("netlink/*.yaml")

    dyn_exclude_patterns.append("devicetree/bindings/**.yaml")

    dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")



# Properly handle include/exclude patterns

# ----------------------------------------
@@ -102,12 +111,12 @@ extensions = [ 
    "kernel_include",

    "kfigure",

    "maintainers_include",

    "parser_yaml",

    "rstFlatTable",

    "sphinx.ext.autosectionlabel",

    "sphinx.ext.ifconfig",

    "translations",

]



# 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.

# Those needed to be escaped by using c_id_attributes[] array
@@ -204,10 +213,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 encoding of source files.

# source_encoding = 'utf-8-sig'

Documentation/networking/index.rst

+1 −1
Original line number Diff line number Diff line
@@ -57,7 +57,7 @@ Contents: 
   filter

   generic-hdlc

   generic_netlink

   netlink_spec/index

   ../netlink/specs/index

   gen_stats

   gtp

   ila

Documentation/networking/netlink_spec/readme.txt

deleted100644 → 0
+0 −4
Original line number Diff line number Diff line 
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.