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