Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

Mauro Carvalho Chehab
2026-05-05T05:45:40Z

On Tue, 5 May 2026 02:20:45 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Also, with time, maintainers may change their employers while still
> > keeping their maintainership status.
> >
> > So, I'd say that whatever is there at the "P" entry, or where it is
> > located (either on a ReST file at the Kernel or on some external URL),
> > it should reflect the model that a maintainer or subsystem community
> > that actively participate at the Kernel development agrees with.
> > This should be vendor-agnostic.
>
> I am not sure what you mean. By "vendored" I don't mean
> companies/employers, I mean that the file comes from an upstream
> repository:
>
> https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
>
> Nevertheless, it is true that this really is a special case, in that
> the upstream project decided to provide something that could then be
> fit into the `P:` field.
>
> One could say "let's ask them to do rst upstream", but to be honest,
> it is simpler to just put a hyperlink to GitHub's rendered file.
> Markdown is anyway a better fit for their file.

Ok. Then it P entry could be:

P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md

> > Generating on the fly is a bad idea, as when one uses:
> >
> > make O=SOME_DIR
> >
> > It is expected that the original source directory will remain
> > untouched.
>
> I am not sure why that would be a problem -- the output would be in
> `objtree`, not in `srctree`, as usual.

No, this won't work. See sphinx-build help:

$ sphinx-build --help
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
...

positional arguments:
SOURCE_DIR path to documentation source files
OUTPUT_DIR path to output directory
filenames (optional) a list of specific files to rebuild. Ignored if --write-all is specified

The way Sphinx works is that it will consider a source file
only for stuff inside the SOURCE_DIR positional parameter passed to
sphinx-build. It handles SOURCE_DIR the same way chroot does:
assuming that you add at toctable inside Documentation/index.rst
(e.g on its root level) something like like this:

/DIR/file.rst
../DIR/file.rst
../../../../../../../../../DIR/file.rst

They all will be interpreted as:
{SOURCE_DIR}/DIR/file.rst

Making impossible to reference any file at the OUTPUT_DIR, except
if you place OUTPUT_DIR inside SOURCE_DIR.

On normal builds, where we have "output" dir inside "Documentation",
this works, but when O=DIR is used, the output directory is
typically elsewhere, which effectively breaks O=DIR support.

Besides it, Sphinx makes a 1:1 map between a source rst file
and a destination html file (for make htmldocs).

MAINTAINERS is actually a good example of such limitation: I would
love to produce per-subsystem output files from a single
maintainers.rst file, but Sphinx doesn't allow that.

>
> > I suggested pandoc as a one-time conversion if one wants to migrate
> > from MD to rst, as for simple documents like this one, it works
> > fine.
>
> They are the maintainers, so it is up to them, but it is simpler to
> use a hyperlink.
>
> (The file is trivial, i.e. the conversion can be done in a moment
> without `pandoc`).

Ok.

Thanks,
Mauro