Documentation/sphinx/maintainers_include.py

   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             # 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 []