doc-rst: Programmatically render MAINTAINERS into ReST
authorKees Cook <keescook@chromium.org>
Tue, 1 Oct 2019 18:25:32 +0000 (11:25 -0700)
committerJonathan Corbet <corbet@lwn.net>
Wed, 2 Oct 2019 16:03:17 +0000 (10:03 -0600)
commitaa204855281389fe25c0049190531ba67e043d99
treeca2ae79fb7353838ceebac98b36a7aaea780b194
parent1b1438b5351f54d3fb8b3cc1579dea7668b03ca0
doc-rst: Programmatically render MAINTAINERS into ReST

In order to have the MAINTAINERS file visible in the rendered ReST
output, this makes some small changes to the existing MAINTAINERS file
to allow for better machine processing, and adds a new Sphinx directive
"maintainers-include" to perform the rendering.

Features include:
- Per-subsystem reference links: subsystem maintainer entries can be
  trivially linked to both internally and external. For example:
  https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing

- Internally referenced .rst files are linked so they can be followed
  when browsing the resulting rendering. This allows, for example, the
  future addition of maintainer profiles to be automatically linked.

- Field name expansion: instead of the short fields (e.g. "M", "F",
  "K"), use the indicated inline "full names" for the fields (which are
  marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
  is more human readable. Email lists are additionally comma-separated.
  For example:

    SECURE COMPUTING
Mail:   Kees Cook <keescook@chromium.org>
Reviewer: Andy Lutomirski <luto@amacapital.net>,
  Will Drewry <wad@chromium.org>
SCM:   git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
Status:   Supported
Files:   kernel/seccomp.c include/uapi/linux/seccomp.h
  include/linux/seccomp.h tools/testing/selftests/seccomp/*
  tools/testing/selftests/kselftest_harness.h
  userspace-api/seccomp_filter
Content regex: \bsecure_computing \bTIF_SECCOMP\b

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/conf.py
Documentation/process/index.rst
Documentation/process/maintainers.rst [new file with mode: 0644]
Documentation/sphinx/maintainers_include.py [new file with mode: 0755]
MAINTAINERS