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 6u""" 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 20import sys 21import re 22import os.path 23 24from docutils import statemachine 25from docutils.utils.error_reporting import ErrorString 26from docutils.parsers.rst import Directive 27from docutils.parsers.rst.directives.misc import Include 28 29__version__ = '1.0' 30 31def 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 39class 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 # Have we reached the end of the preformatted Descriptions text? 65 if descriptions and line.startswith('Maintainers'): 66 descriptions = False 67 # Ensure a blank line following the last "|"-prefixed line. 68 result.append("") 69 70 # Start subsystem processing? This is to skip processing the text 71 # between the Maintainers heading and the first subsystem name. 72 if maintainers and not subsystems: 73 if re.search('^[A-Z0-9]', line): 74 subsystems = True 75 76 # Drop needless input whitespace. 77 line = line.rstrip() 78 79 # Linkify all non-wildcard refs to ReST files in Documentation/. 80 pat = r'(Documentation/([^\s\?\*]*)\.rst)' 81 m = re.search(pat, line) 82 if m: 83 # maintainers.rst is in a subdirectory, so include "../". 84 line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) 85 86 # Check state machine for output rendering behavior. 87 output = None 88 if descriptions: 89 # Escape the escapes in preformatted text. 90 output = "| %s" % (line.replace("\\", "\\\\")) 91 # Look for and record field letter to field name mappings: 92 # R: Designated *reviewer*: FullName <address@domain> 93 m = re.search(r"\s(\S):\s", line) 94 if m: 95 field_letter = m.group(1) 96 if field_letter and not field_letter in fields: 97 m = re.search(r"\*([^\*]+)\*", line) 98 if m: 99 fields[field_letter] = m.group(1) 100 elif subsystems: 101 # Skip empty lines: subsystem parser adds them as needed. 102 if len(line) == 0: 103 continue 104 # Subsystem fields are batched into "field_content" 105 if line[1] != ':': 106 # Render a subsystem entry as: 107 # SUBSYSTEM NAME 108 # ~~~~~~~~~~~~~~ 109 110 # Flush pending field content. 111 output = field_content + "\n\n" 112 field_content = "" 113 114 # Collapse whitespace in subsystem name. 115 heading = re.sub(r"\s+", " ", line) 116 output = output + "%s\n%s" % (heading, "~" * len(heading)) 117 field_prev = "" 118 else: 119 # Render a subsystem field as: 120 # :Field: entry 121 # entry... 122 field, details = line.split(':', 1) 123 details = details.strip() 124 125 # Mark paths (and regexes) as literal text for improved 126 # readability and to escape any escapes. 127 if field in ['F', 'N', 'X', 'K']: 128 # But only if not already marked :) 129 if not ':doc:' in details: 130 details = '``%s``' % (details) 131 132 # Comma separate email field continuations. 133 if field == field_prev and field_prev in ['M', 'R', 'L']: 134 field_content = field_content + "," 135 136 # Do not repeat field names, so that field entries 137 # will be collapsed together. 138 if field != field_prev: 139 output = field_content + "\n" 140 field_content = ":%s:" % (fields.get(field, field)) 141 field_content = field_content + "\n\t%s" % (details) 142 field_prev = field 143 else: 144 output = line 145 146 # Re-split on any added newlines in any above parsing. 147 if output != None: 148 for separated in output.split('\n'): 149 result.append(separated) 150 151 # Update the state machine when we find heading separators. 152 if line.startswith('----------'): 153 if prev.startswith('Descriptions'): 154 descriptions = True 155 if prev.startswith('Maintainers'): 156 maintainers = True 157 158 # Retain previous line for state machine transitions. 159 prev = line 160 161 # Flush pending field contents. 162 if field_content != "": 163 for separated in field_content.split('\n'): 164 result.append(separated) 165 166 output = "\n".join(result) 167 # For debugging the pre-rendered results... 168 #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) 169 170 self.state_machine.insert_input( 171 statemachine.string2lines(output), path) 172 173 def run(self): 174 """Include the MAINTAINERS file as part of this reST file.""" 175 if not self.state.document.settings.file_insertion_enabled: 176 raise self.warning('"%s" directive disabled.' % self.name) 177 178 # Walk up source path directories to find Documentation/../ 179 path = self.state_machine.document.attributes['source'] 180 path = os.path.realpath(path) 181 tail = path 182 while tail != "Documentation" and tail != "": 183 (path, tail) = os.path.split(path) 184 185 # Append "MAINTAINERS" 186 path = os.path.join(path, "MAINTAINERS") 187 188 try: 189 self.state.document.settings.record_dependencies.add(path) 190 lines = self.parse_maintainers(path) 191 except IOError as error: 192 raise self.severe('Problems with "%s" directive path:\n%s.' % 193 (self.name, ErrorString(error))) 194 195 return [] 196