Em Fri, 13 Jun 2025 12:29:34 +0100
Donald Hunter [off-list ref] escreveu:

Mauro Carvalho Chehab [off-list ref] writes:

quoted

Add a simple sphinx.Parser class meant to handle yaml files.

For now, it just replaces a yaml file by a simple ReST
code. I opted to do this way, as this patch can be used as
basis for new file format parsers. We may use this as an
example to parse other types of files.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/parser_yaml.py | 63 +++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100755 Documentation/sphinx/parser_yaml.py  

It's not a generic yaml parser so the file should be
netlink_doc_generator.py or something.

There's no way I'm aware of to have two yaml parsers. So, assuming that
some other subsystem would also use yaml (*), the same parser will need to
handle yaml files from different parts.

That's why I opted to have a generic name here. Besides that, there's
nothing there which is specific to Netlink, as the actual parser is
implemented inside a class on a separate file.

(*) as I said, media is considering using yaml for sensors. Nothing yet
    materialized, as we just had our summit last month. Yet, as DT also
    uses yaml, so I won't doubt that other subsystems may end using it
    as well.

quoted

diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
new file mode 100755
index 000000000000..b3cde9cf7aac
--- /dev/null
+++ b/Documentation/sphinx/parser_yaml.py

@@ -0,0 +1,63 @@
+"""
+Sphinx extension for processing YAML files
+"""
+
+import os
+
+from docutils.parsers.rst import Parser as RSTParser
+from docutils.statemachine import ViewList
+
+from sphinx.util import logging
+from sphinx.parsers import Parser
+
+from pprint import pformat
+
+logger = logging.getLogger(__name__)
+
+class YamlParser(Parser):
+    """Custom parser for YAML files."""  

The class is only intended to be a netlink doc generator so I sugget
calling it NetlinkDocGenerator

See above.

quoted

+
+    supported = ('yaml', 'yml')  

I don't think we need to support the .yml extension.

Ok, will drop "yml".

quoted

+
+    # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
+    def parse(self, inputstring, document):
+        """Parse YAML and generate a document tree."""
+
+        self.setup_parse(inputstring, document)
+
+        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)
+
+            rst_parser = RSTParser()
+            rst_parser.parse('\n'.join(result), document)
+
+        except Exception as e:
+            document.reporter.error("YAML parsing error: %s" % pformat(e))
+
+        self.finish_parse()
+
+def setup(app):
+    """Setup function for the Sphinx extension."""
+
+    # Add YAML parser
+    app.add_source_parser(YamlParser)
+    app.add_source_suffix('.yaml', 'yaml')
+    app.add_source_suffix('.yml', 'yaml')  

No need to support the .yml extension.

Ok.

quoted

+
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }  

Thanks,
Mauro