mirror of
https://xff.cz/git/u-boot/
synced 2025-10-31 18:35:42 +01:00
Revert "doc: update Kernel documentation build system"
Unfortunately we now see a number of now-fatal warnings about duplicate
labels. It is often unclear how best to re-write the document in
question to not duplicate these otherwise logical headings.
This reverts commit 10a1df3cd4.
Signed-off-by: Tom Rini <trini@konsulko.com>
This commit is contained in:
Tom Rini
@@ -1,197 +0,0 @@
|
||||
#!/usr/bin/env python
|
||||
# SPDX-License-Identifier: GPL-2.0
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=R0903, C0330, R0914, R0912, E0401
|
||||
|
||||
u"""
|
||||
maintainers-include
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Implementation of the ``maintainers-include`` reST-directive.
|
||||
|
||||
:copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
|
||||
:license: GPL Version 2, June 1991 see linux/COPYING for details.
|
||||
|
||||
The ``maintainers-include`` reST-directive performs extensive parsing
|
||||
specific to the Linux kernel's standard "MAINTAINERS" file, in an
|
||||
effort to avoid needing to heavily mark up the original plain text.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import re
|
||||
import os.path
|
||||
|
||||
from docutils import statemachine
|
||||
from docutils.utils.error_reporting import ErrorString
|
||||
from docutils.parsers.rst import Directive
|
||||
from docutils.parsers.rst.directives.misc import Include
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
def setup(app):
|
||||
app.add_directive("maintainers-include", MaintainersInclude)
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
|
||||
class MaintainersInclude(Include):
|
||||
u"""MaintainersInclude (``maintainers-include``) directive"""
|
||||
required_arguments = 0
|
||||
|
||||
def parse_maintainers(self, path):
|
||||
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
|
||||
|
||||
result = list()
|
||||
result.append(".. _maintainers:")
|
||||
result.append("")
|
||||
|
||||
# Poor man's state machine.
|
||||
descriptions = False
|
||||
maintainers = False
|
||||
subsystems = False
|
||||
|
||||
# Field letter to field name mapping.
|
||||
field_letter = None
|
||||
fields = dict()
|
||||
|
||||
prev = None
|
||||
field_prev = ""
|
||||
field_content = ""
|
||||
|
||||
for line in open(path):
|
||||
if sys.version_info.major == 2:
|
||||
line = unicode(line, 'utf-8')
|
||||
# Have we reached the end of the preformatted Descriptions text?
|
||||
if descriptions and line.startswith('Maintainers'):
|
||||
descriptions = False
|
||||
# Ensure a blank line following the last "|"-prefixed line.
|
||||
result.append("")
|
||||
|
||||
# Start subsystem processing? This is to skip processing the text
|
||||
# between the Maintainers heading and the first subsystem name.
|
||||
if maintainers and not subsystems:
|
||||
if re.search('^[A-Z0-9]', line):
|
||||
subsystems = True
|
||||
|
||||
# Drop needless input whitespace.
|
||||
line = line.rstrip()
|
||||
|
||||
# Linkify all non-wildcard refs to ReST files in Documentation/.
|
||||
pat = '(Documentation/([^\s\?\*]*)\.rst)'
|
||||
m = re.search(pat, line)
|
||||
if m:
|
||||
# maintainers.rst is in a subdirectory, so include "../".
|
||||
line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
|
||||
|
||||
# Check state machine for output rendering behavior.
|
||||
output = None
|
||||
if descriptions:
|
||||
# Escape the escapes in preformatted text.
|
||||
output = "| %s" % (line.replace("\\", "\\\\"))
|
||||
# Look for and record field letter to field name mappings:
|
||||
# R: Designated *reviewer*: FullName <address@domain>
|
||||
m = re.search("\s(\S):\s", line)
|
||||
if m:
|
||||
field_letter = m.group(1)
|
||||
if field_letter and not field_letter in fields:
|
||||
m = re.search("\*([^\*]+)\*", line)
|
||||
if m:
|
||||
fields[field_letter] = m.group(1)
|
||||
elif subsystems:
|
||||
# Skip empty lines: subsystem parser adds them as needed.
|
||||
if len(line) == 0:
|
||||
continue
|
||||
# Subsystem fields are batched into "field_content"
|
||||
if line[1] != ':':
|
||||
# Render a subsystem entry as:
|
||||
# SUBSYSTEM NAME
|
||||
# ~~~~~~~~~~~~~~
|
||||
|
||||
# Flush pending field content.
|
||||
output = field_content + "\n\n"
|
||||
field_content = ""
|
||||
|
||||
# Collapse whitespace in subsystem name.
|
||||
heading = re.sub("\s+", " ", line)
|
||||
output = output + "%s\n%s" % (heading, "~" * len(heading))
|
||||
field_prev = ""
|
||||
else:
|
||||
# Render a subsystem field as:
|
||||
# :Field: entry
|
||||
# entry...
|
||||
field, details = line.split(':', 1)
|
||||
details = details.strip()
|
||||
|
||||
# Mark paths (and regexes) as literal text for improved
|
||||
# readability and to escape any escapes.
|
||||
if field in ['F', 'N', 'X', 'K']:
|
||||
# But only if not already marked :)
|
||||
if not ':doc:' in details:
|
||||
details = '``%s``' % (details)
|
||||
|
||||
# Comma separate email field continuations.
|
||||
if field == field_prev and field_prev in ['M', 'R', 'L']:
|
||||
field_content = field_content + ","
|
||||
|
||||
# Do not repeat field names, so that field entries
|
||||
# will be collapsed together.
|
||||
if field != field_prev:
|
||||
output = field_content + "\n"
|
||||
field_content = ":%s:" % (fields.get(field, field))
|
||||
field_content = field_content + "\n\t%s" % (details)
|
||||
field_prev = field
|
||||
else:
|
||||
output = line
|
||||
|
||||
# Re-split on any added newlines in any above parsing.
|
||||
if output != None:
|
||||
for separated in output.split('\n'):
|
||||
result.append(separated)
|
||||
|
||||
# Update the state machine when we find heading separators.
|
||||
if line.startswith('----------'):
|
||||
if prev.startswith('Descriptions'):
|
||||
descriptions = True
|
||||
if prev.startswith('Maintainers'):
|
||||
maintainers = True
|
||||
|
||||
# Retain previous line for state machine transitions.
|
||||
prev = line
|
||||
|
||||
# Flush pending field contents.
|
||||
if field_content != "":
|
||||
for separated in field_content.split('\n'):
|
||||
result.append(separated)
|
||||
|
||||
output = "\n".join(result)
|
||||
# For debugging the pre-rendered results...
|
||||
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
|
||||
|
||||
self.state_machine.insert_input(
|
||||
statemachine.string2lines(output), path)
|
||||
|
||||
def run(self):
|
||||
"""Include the MAINTAINERS file as part of this reST file."""
|
||||
if not self.state.document.settings.file_insertion_enabled:
|
||||
raise self.warning('"%s" directive disabled.' % self.name)
|
||||
|
||||
# Walk up source path directories to find Documentation/../
|
||||
path = self.state_machine.document.attributes['source']
|
||||
path = os.path.realpath(path)
|
||||
tail = path
|
||||
while tail != "Documentation" and tail != "":
|
||||
(path, tail) = os.path.split(path)
|
||||
|
||||
# Append "MAINTAINERS"
|
||||
path = os.path.join(path, "MAINTAINERS")
|
||||
|
||||
try:
|
||||
self.state.document.settings.record_dependencies.add(path)
|
||||
lines = self.parse_maintainers(path)
|
||||
except IOError as error:
|
||||
raise self.severe('Problems with "%s" directive path:\n%s.' %
|
||||
(self.name, ErrorString(error)))
|
||||
|
||||
return []
|
||||
Reference in New Issue
Block a user