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