[PATCH v2 10/12] docs: sphinx: parser_yaml.py: add Netlink specs parser

Mauro Carvalho Chehab
2025-06-12T10:32:24Z

Place the code at parser_yaml.py to handle Netlink specs. All
other yaml files are ignored.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.pylintrc | 2 +-
Documentation/sphinx/parser_yaml.py | 39 +++++++++++++++++++++--------
2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/.pylintrc b/.pylintrc
index 30b8ae1659f8..f1d21379254b 100644
--- a/.pylintrc
+++ b/.pylintrc
@@ -1,2 +1,2 @@
[MASTER]
-init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi"]'
+init-hook='import sys; sys.path += ["scripts/lib", "scripts/lib/kdoc", "scripts/lib/abi"]'
diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
index b3cde9cf7aac..eb32e3249274 100755
--- a/Documentation/sphinx/parser_yaml.py
+++ b/Documentation/sphinx/parser_yaml.py
@@ -3,6 +3,10 @@ Sphinx extension for processing YAML files
"""

import os
+import re
+import sys
+
+from pprint import pformat

from docutils.parsers.rst import Parser as RSTParser
from docutils.statemachine import ViewList
@@ -10,7 +14,10 @@ from docutils.statemachine import ViewList
from sphinx.util import logging
from sphinx.parsers import Parser

-from pprint import pformat
+srctree = os.path.abspath(os.environ["srctree"])
+sys.path.insert(0, os.path.join(srctree, "scripts/lib"))
+
+from netlink_yml_parser import NetlinkYamlParser # pylint: disable=C0413

logger = logging.getLogger(__name__)

@@ -19,8 +26,9 @@ class YamlParser(Parser):

supported = ('yaml', 'yml')

- # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
- def parse(self, inputstring, document):
+ netlink_parser = NetlinkYamlParser()
+
+ def do_parse(self, inputstring, document, msg):
"""Parse YAML and generate a document tree."""

self.setup_parse(inputstring, document)
@@ -28,14 +36,6 @@ class YamlParser(Parser):
result = ViewList()

try:
- # FIXME: Test logic to generate some ReST content
- basename = os.path.basename(document.current_source)
- title = os.path.splitext(basename)[0].replace('_', ' ').title()
-
- msg = f"{title}\n"
- msg += "=" * len(title) + "\n\n"
- msg += "Something\n"
-
# Parse message with RSTParser
for i, line in enumerate(msg.split('\n')):
result.append(line, document.current_source, i)
@@ -48,6 +48,23 @@ class YamlParser(Parser):

self.finish_parse()

+ # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
+ def parse(self, inputstring, document):
+ """Check if a YAML is meant to be parsed."""
+
+ fname = document.current_source
+
+ # Handle netlink yaml specs
+ if re.search("/netlink/specs/", fname):
+ if fname.endswith("index.yaml"):
+ msg = self.netlink_parser.generate_main_index_rst(fname, None)
+ else:
+ msg = self.netlink_parser.parse_yaml_file(fname)
+
+ self.do_parse(inputstring, document, msg)
+
+ # All other yaml files are ignored
+
def setup(app):
"""Setup function for the Sphinx extension."""

--
2.49.0