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

Miguel Ojeda
2026-05-04T23:35:09Z

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).

> 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?

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

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. But
pandoc is a heavy dependency to request, no?

Cheers,
Miguel