[PATCH 0/2] docs: Programmatically render MAINTAINERS into ReST

Kees Cook
2019-09-24T23:02:16Z

Commit log from Patch 2 repeated here for cover letter:

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

---
Kees Cook (2):
doc-rst: Reduce CSS padding around Field
doc-rst: Programmatically render MAINTAINERS into ReST

Documentation/conf.py | 3 +-
Documentation/process/index.rst | 1 +
Documentation/process/maintainers.rst | 1 +
.../sphinx-static/theme_overrides.css | 10 +
Documentation/sphinx/maintainers_include.py | 194 ++++++++++++++++++
MAINTAINERS | 62 +++---
6 files changed, 240 insertions(+), 31 deletions(-)
create mode 100644 Documentation/process/maintainers.rst
create mode 100755 Documentation/sphinx/maintainers_include.py

--
2.17.1