doc-rst: Programmatically render MAINTAINERS into ReST

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',

              'kfigure', 'sphinx.ext.ifconfig', 'automarkup']

              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',

              'maintainers_include']

# The name of the math extension changed on Sphinx 1.4

if (major == 1 and minor > 3) or (major > 1):

   kernel-docs

   deprecated

   embargoed-hardware-issues

   maintainers

These are some overall technical guides that have been put here for now for

lack of a better place.

.. maintainers-include::

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

List of maintainers and how to submit kernel changes

====================================================

Please try to follow the guidelines below.  This will make things

easier on the maintainers.  Not all of these guidelines matter for every

trivial patch so apply some common sense.

1.	Always _test_ your changes, however small, on at least 4 or

Tips for patch submitters

-------------------------

1.	Always *test* your changes, however small, on at least 4 or

	5 people, preferably many more.

2.	Try to release a few ALPHA test versions to the net. Announce

	testing and await feedback.

5.	Make a patch available to the relevant maintainer in the list. Use

	'diff -u' to make the patch easy to merge. Be prepared to get your

	``diff -u`` to make the patch easy to merge. Be prepared to get your

	changes sent back with seemingly silly requests about formatting

	and variable names.  These aren't as silly as they seem. One

	job the maintainers (and especially Linus) do is to keep things

	See Documentation/process/coding-style.rst for guidance here.

	PLEASE CC: the maintainers and mailing lists that are generated

	by scripts/get_maintainer.pl.  The results returned by the

	by ``scripts/get_maintainer.pl.`` The results returned by the

	script will be best if you have git installed and are making

	your changes in a branch derived from Linus' latest git tree.

	See Documentation/process/submitting-patches.rst for details.

	not represent an immediate threat and are better handled publicly,

	and ideally, should come with a patch proposal. Please do not send

	automated reports to this list either. Such bugs will be handled

	better and faster in the usual public places.

	better and faster in the usual public places. See

	Documentation/admin-guide/security-bugs.rst for details.

8.	Happy hacking.

Descriptions of section entries:

Descriptions of section entries

-------------------------------

	P: Person (obsolete)

	M: Mail patches to: FullName <address@domain>

	R: Designated reviewer: FullName <address@domain>

	M: *Mail* patches to: FullName <address@domain>

	R: Designated *Reviewer*: FullName <address@domain>

	   These reviewers should be CCed on patches.

	L: Mailing list that is relevant to this area

	W: Web-page with status/info

	B: URI for where to file bugs. A web-page with detailed bug

	L: *Mailing list* that is relevant to this area

	W: *Web-page* with status/info

	B: URI for where to file *bugs*. A web-page with detailed bug

	   filing info, a direct bug tracker link, or a mailto: URI.

	C: URI for chat protocol, server and channel where developers

	C: URI for *chat* protocol, server and channel where developers

	   usually hang out, for example irc://server/channel.

	Q: Patchwork web based patch tracking system site

	T: SCM tree type and location.

	Q: *Patchwork* web based patch tracking system site

	T: *SCM* tree type and location.

	   Type is one of: git, hg, quilt, stgit, topgit

	S: Status, one of the following:

	S: *Status*, one of the following:

	   Supported:	Someone is actually paid to look after this.

	   Maintained:	Someone actually looks after it.

	   Odd Fixes:	It has a maintainer but they don't have time to do

	   Obsolete:	Old code. Something tagged obsolete generally means

			it has been replaced by a better system and you

			should be using that.

	F: Files and directories with wildcard patterns.

	F: *Files* and directories wildcard patterns.

	   A trailing slash includes all files and subdirectory files.

	   F:	drivers/net/	all files in and below drivers/net

	   F:	drivers/net/*	all files in drivers/net, but not below

	   F:	*/net/*		all files in "any top level directory"/net

	   One pattern per line.  Multiple F: lines acceptable.

	N: Files and directories with regex patterns.

	N: Files and directories *Regex* patterns.

	   N:	[^a-z]tegra	all files whose path contains the word tegra

	   One pattern per line.  Multiple N: lines acceptable.

	   scripts/get_maintainer.pl has different behavior for files that

	   get_maintainer will not look at git log history when an F: pattern

	   match occurs.  When an N: match occurs, git log history is used

	   to also notify the people that have git commit signatures.

	X: Files and directories that are NOT maintained, same rules as F:

	   Files exclusions are tested before file matches.

	X: *Excluded* files and directories that are NOT maintained, same

	   rules as F:. Files exclusions are tested before file matches.

	   Can be useful for excluding a specific subdirectory, for instance:

	   F:	net/

	   X:	net/ipv6/

	   matches all files in and below net excluding net/ipv6/

	K: Keyword perl extended regex pattern to match content in a

	   patch or file.  For instance:

	K: *Content regex* (perl extended) pattern match in a patch or file.

	   For instance:

	   K: of_get_profile

	      matches patches or files that contain "of_get_profile"

	   K: \b(printk|pr_(info|err))\b

	      printk, pr_info or pr_err

	   One regex pattern per line.  Multiple K: lines acceptable.

Note: For the hard of thinking, this list is meant to remain in alphabetical

order. If you could add yourselves to it in alphabetical order that would be

so much easier [Ed]

Maintainers List (try to look for most precise areas first)

Maintainers List

----------------

		-----------------------------------

.. note:: When reading this list, please look for the most precise areas

          first. When adding to this list, please keep the entries in

          alphabetical order.

3C59X NETWORK DRIVER

M:	Steffen Klassert <klassert@kernel.org>