Commit c4f72d37 authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

Merge tag 'docs/v6.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-docs 

Mauro Carvalho Chehab says:

====================
add a generic yaml parser integrated with Netlink specs generation

- An YAML parser Sphinx plugin, integrated with Netlink YAML doc
  parser.

The patch content is identical to my v10 submission:
https://lore.kernel.org/cover.1753718185.git.mchehab+huawei@kernel.org

* tag 'docs/v6.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-docs:
  sphinx: parser_yaml.py: fix line numbers information
  docs: parser_yaml.py: fix backward compatibility with old docutils
  docs: parser_yaml.py: add support for line numbers from the parser
  tools: netlink_yml_parser.py: add line numbers to parsed data
  MAINTAINERS: add netlink_yml_parser.py to linux-doc
  docs: netlink: remove obsolete .gitignore from unused directory
  tools: ynl_gen_rst.py: drop support for generating index files
  docs: uapi: netlink: update netlink specs link
  docs: use parser_yaml extension to handle Netlink specs
  docs: sphinx: add a parser for yaml files for Netlink specs
  tools: ynl_gen_rst.py: cleanup coding style
  docs: netlink: index.rst: add a netlink index file
  tools: ynl_gen_rst.py: Split library from command line tool
  docs: netlink: netlink-raw.rst: use :ref: instead of :doc:
====================

Link: https://patch.msgid.link/20250812113329.356c93c2@foz.lan


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parents f24775c3 47459937

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/netlink/specs/index.rst

0 → 100644
+13 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



.. _specs:



=============================

Netlink Family Specifications

=============================



.. toctree::

   :maxdepth: 1

   :glob:



   *

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/.gitignore

deleted100644 → 0
+0 −1
Original line number Diff line number Diff line 
*.rst