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

[Mauro Carvalho Chehab]

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

> On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
> <mchehab+huawei@xxxxxxxxxx> 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