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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Tue, 5 May 2026 01:34:55 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Mon, May 4, 2026 at 10:26 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > It is not written there, but by file, it would actually be expected
> > a file within Documentation in ReST format ;-)  
> 
> I don't know! :)
> 
> You are right that we encourage rst in Doc/, but for vendored stuff,
> it makes sense to allow other paths (and other formats).
> 
> > I'm afraid that this is not possible. Sphinx doesn't allow
> > hyperlinks to point to files outside the documentation root
> > (which is Documentation/ when SPHINXDIRS is not used).  
> 
> Hmm... That could actually be useful for other things (e.g. links to
> particular source files).

I know but this is part of Sphinx logic to protect against dir
traversal. We added an include extension to allow including
source files, but it will still require a file inside Documentation.

As a general rule, all files generated at Sphinx output directory
needs a source file inside Documentation/ directory.

> 
> > IMO the best would be to run:
> >
> >         pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
> >         sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS
> >
> > This way, it will generate a proper hyperlink.  
> 
> You mean on the fly, or committing it?

I meant committing it.

> If you mean committing, then I think it would be best to avoid
> modifying vendored files.

Not sure what you meant by "vendored files". Maintainer's profile
is not something where vendors are the only ones ruling it. Instead,
it has to be aligned with the Kernel development process and Kernel
maintainers, independently if they're working on a particular
vendor or not.

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.

> If you mean on the fly, then that could actually be quite interesting,
> and we recently discussed e.g. whether to have a particular file in
> .md vs .rst and whether we could handle the conversion out-of-tree
> just for that reason. So if it could be done in-tree, even better. 

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. 

> But pandoc is a heavy dependency to request, no?

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. 

In summary, I can see 3 possible alternatives to have the Kernel
generated documentation to have a link to the profile:

1. convert it from MD to RST and keep only at the Kernel, inside
   Documentation/;
2. convert it from MD to RST and keep both at the Kernel and at
   Gitlab/Github (both supports .rst files natively);
3. change the "P" entry to point to an external URL.

Regards,
Mauro