Commit | Line | Data |
---|---|---|
aa204855 KC |
1 | #!/usr/bin/env python |
2 | # SPDX-License-Identifier: GPL-2.0 | |
3 | # -*- coding: utf-8; mode: python -*- | |
4 | # pylint: disable=R0903, C0330, R0914, R0912, E0401 | |
5 | ||
6 | u""" | |
7 | maintainers-include | |
8 | ~~~~~~~~~~~~~~~~~~~ | |
9 | ||
10 | Implementation of the ``maintainers-include`` reST-directive. | |
11 | ||
12 | :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org> | |
13 | :license: GPL Version 2, June 1991 see linux/COPYING for details. | |
14 | ||
15 | The ``maintainers-include`` reST-directive performs extensive parsing | |
16 | specific to the Linux kernel's standard "MAINTAINERS" file, in an | |
17 | effort to avoid needing to heavily mark up the original plain text. | |
18 | """ | |
19 | ||
20 | import sys | |
21 | import re | |
22 | import os.path | |
23 | ||
24 | from docutils import statemachine | |
25 | from docutils.utils.error_reporting import ErrorString | |
26 | from docutils.parsers.rst import Directive | |
27 | from docutils.parsers.rst.directives.misc import Include | |
28 | ||
29 | __version__ = '1.0' | |
30 | ||
31 | def setup(app): | |
32 | app.add_directive("maintainers-include", MaintainersInclude) | |
33 | return dict( | |
34 | version = __version__, | |
35 | parallel_read_safe = True, | |
36 | parallel_write_safe = True | |
37 | ) | |
38 | ||
39 | class MaintainersInclude(Include): | |
40 | u"""MaintainersInclude (``maintainers-include``) directive""" | |
41 | required_arguments = 0 | |
42 | ||
43 | def parse_maintainers(self, path): | |
44 | """Parse all the MAINTAINERS lines into ReST for human-readability""" | |
45 | ||
46 | result = list() | |
47 | result.append(".. _maintainers:") | |
48 | result.append("") | |
49 | ||
50 | # Poor man's state machine. | |
51 | descriptions = False | |
52 | maintainers = False | |
53 | subsystems = False | |
54 | ||
55 | # Field letter to field name mapping. | |
56 | field_letter = None | |
57 | fields = dict() | |
58 | ||
59 | prev = None | |
60 | field_prev = "" | |
61 | field_content = "" | |
62 | ||
63 | for line in open(path): | |
64 | if sys.version_info.major == 2: | |
65 | line = unicode(line, 'utf-8') | |
66 | # Have we reached the end of the preformatted Descriptions text? | |
67 | if descriptions and line.startswith('Maintainers'): | |
68 | descriptions = False | |
69 | # Ensure a blank line following the last "|"-prefixed line. | |
70 | result.append("") | |
71 | ||
72 | # Start subsystem processing? This is to skip processing the text | |
73 | # between the Maintainers heading and the first subsystem name. | |
74 | if maintainers and not subsystems: | |
75 | if re.search('^[A-Z0-9]', line): | |
76 | subsystems = True | |
77 | ||
78 | # Drop needless input whitespace. | |
79 | line = line.rstrip() | |
80 | ||
81 | # Linkify all non-wildcard refs to ReST files in Documentation/. | |
82 | pat = '(Documentation/([^\s\?\*]*)\.rst)' | |
83 | m = re.search(pat, line) | |
84 | if m: | |
85 | # maintainers.rst is in a subdirectory, so include "../". | |
86 | line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) | |
87 | ||
88 | # Check state machine for output rendering behavior. | |
89 | output = None | |
90 | if descriptions: | |
91 | # Escape the escapes in preformatted text. | |
92 | output = "| %s" % (line.replace("\\", "\\\\")) | |
93 | # Look for and record field letter to field name mappings: | |
94 | # R: Designated *reviewer*: FullName <address@domain> | |
95 | m = re.search("\s(\S):\s", line) | |
96 | if m: | |
97 | field_letter = m.group(1) | |
98 | if field_letter and not field_letter in fields: | |
99 | m = re.search("\*([^\*]+)\*", line) | |
100 | if m: | |
101 | fields[field_letter] = m.group(1) | |
102 | elif subsystems: | |
103 | # Skip empty lines: subsystem parser adds them as needed. | |
104 | if len(line) == 0: | |
105 | continue | |
106 | # Subsystem fields are batched into "field_content" | |
107 | if line[1] != ':': | |
108 | # Render a subsystem entry as: | |
109 | # SUBSYSTEM NAME | |
110 | # ~~~~~~~~~~~~~~ | |
111 | ||
112 | # Flush pending field content. | |
113 | output = field_content + "\n\n" | |
114 | field_content = "" | |
115 | ||
116 | # Collapse whitespace in subsystem name. | |
117 | heading = re.sub("\s+", " ", line) | |
118 | output = output + "%s\n%s" % (heading, "~" * len(heading)) | |
119 | field_prev = "" | |
120 | else: | |
121 | # Render a subsystem field as: | |
122 | # :Field: entry | |
123 | # entry... | |
124 | field, details = line.split(':', 1) | |
125 | details = details.strip() | |
126 | ||
127 | # Mark paths (and regexes) as literal text for improved | |
128 | # readability and to escape any escapes. | |
129 | if field in ['F', 'N', 'X', 'K']: | |
130 | # But only if not already marked :) | |
131 | if not ':doc:' in details: | |
132 | details = '``%s``' % (details) | |
133 | ||
134 | # Comma separate email field continuations. | |
135 | if field == field_prev and field_prev in ['M', 'R', 'L']: | |
136 | field_content = field_content + "," | |
137 | ||
138 | # Do not repeat field names, so that field entries | |
139 | # will be collapsed together. | |
140 | if field != field_prev: | |
141 | output = field_content + "\n" | |
142 | field_content = ":%s:" % (fields.get(field, field)) | |
143 | field_content = field_content + "\n\t%s" % (details) | |
144 | field_prev = field | |
145 | else: | |
146 | output = line | |
147 | ||
148 | # Re-split on any added newlines in any above parsing. | |
149 | if output != None: | |
150 | for separated in output.split('\n'): | |
151 | result.append(separated) | |
152 | ||
153 | # Update the state machine when we find heading separators. | |
154 | if line.startswith('----------'): | |
155 | if prev.startswith('Descriptions'): | |
156 | descriptions = True | |
157 | if prev.startswith('Maintainers'): | |
158 | maintainers = True | |
159 | ||
160 | # Retain previous line for state machine transitions. | |
161 | prev = line | |
162 | ||
163 | # Flush pending field contents. | |
164 | if field_content != "": | |
165 | for separated in field_content.split('\n'): | |
166 | result.append(separated) | |
167 | ||
168 | output = "\n".join(result) | |
169 | # For debugging the pre-rendered results... | |
170 | #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) | |
171 | ||
172 | self.state_machine.insert_input( | |
173 | statemachine.string2lines(output), path) | |
174 | ||
175 | def run(self): | |
176 | """Include the MAINTAINERS file as part of this reST file.""" | |
177 | if not self.state.document.settings.file_insertion_enabled: | |
178 | raise self.warning('"%s" directive disabled.' % self.name) | |
179 | ||
180 | # Walk up source path directories to find Documentation/../ | |
181 | path = self.state_machine.document.attributes['source'] | |
182 | path = os.path.realpath(path) | |
183 | tail = path | |
184 | while tail != "Documentation" and tail != "": | |
185 | (path, tail) = os.path.split(path) | |
186 | ||
187 | # Append "MAINTAINERS" | |
188 | path = os.path.join(path, "MAINTAINERS") | |
189 | ||
190 | try: | |
191 | self.state.document.settings.record_dependencies.add(path) | |
192 | lines = self.parse_maintainers(path) | |
193 | except IOError as error: | |
194 | raise self.severe('Problems with "%s" directive path:\n%s.' % | |
195 | (self.name, ErrorString(error))) | |
196 | ||
197 | return [] |