xref: /linux/Documentation/sphinx/parser_yaml.py (revision 11d137aaef802fb2a22b917b4d91e800141140c7) 
1# SPDX-License-Identifier: GPL-2.0
2# Copyright 2025 Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
3
4"""
5Sphinx extension for processing YAML files
6"""
7
8import os
9import re
10import sys
11
12from pprint import pformat
13
14from docutils.parsers.rst import Parser as RSTParser
15from docutils.statemachine import ViewList
16
17from sphinx.util import logging
18from sphinx.parsers import Parser
19
20srctree = os.path.abspath(os.environ["srctree"])
21sys.path.insert(0, os.path.join(srctree, "tools/net/ynl/pyynl/lib"))
22
23from doc_generator import YnlDocGenerator        # pylint: disable=C0413
24
25logger = logging.getLogger(__name__)
26
27class YamlParser(Parser):
28    """
29    Kernel parser for YAML files.
30
31    This is a simple sphinx.Parser to handle yaml files inside the
32    Kernel tree that will be part of the built documentation.
33
34    The actual parser function is not contained here: the code was
35    written in a way that parsing yaml for different subsystems
36    can be done from a single dispatcher.
37
38    All it takes to have parse YAML patches is to have an import line:
39
40            from some_parser_code import NewYamlGenerator
41
42    To this module. Then add an instance of the parser with:
43
44            new_parser = NewYamlGenerator()
45
46    and add a logic inside parse() to handle it based on the path,
47    like this:
48
49            if "/foo" in fname:
50                msg = self.new_parser.parse_yaml_file(fname)
51    """
52
53    supported = ('yaml', )
54
55    netlink_parser = YnlDocGenerator()
56
57    def rst_parse(self, inputstring, document, msg):
58        """
59        Receives a ReST content that was previously converted by the
60        YAML parser, adding it to the document tree.
61        """
62
63        self.setup_parse(inputstring, document)
64
65        result = ViewList()
66
67        try:
68            # Parse message with RSTParser
69            for i, line in enumerate(msg.split('\n')):
70                result.append(line, document.current_source, i)
71
72            rst_parser = RSTParser()
73            rst_parser.parse('\n'.join(result), document)
74
75        except Exception as e:
76            document.reporter.error("YAML parsing error: %s" % pformat(e))
77
78        self.finish_parse()
79
80    # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
81    def parse(self, inputstring, document):
82        """Check if a YAML is meant to be parsed."""
83
84        fname = document.current_source
85
86        # Handle netlink yaml specs
87        if "/netlink/specs/" in fname:
88            msg = self.netlink_parser.parse_yaml_file(fname)
89            self.rst_parse(inputstring, document, msg)
90
91        # All other yaml files are ignored
92
93def setup(app):
94    """Setup function for the Sphinx extension."""
95
96    # Add YAML parser
97    app.add_source_parser(YamlParser)
98    app.add_source_suffix('.yaml', 'yaml')
99
100    return {
101        'version': '1.0',
102        'parallel_read_safe': True,
103        'parallel_write_safe': True,
104    }
105