Messages in this thread |  | | Date | Tue, 5 May 2026 02:08:31 +0200 | | From | Mauro Carvalho Chehab <> | | Subject | Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries |
| |
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
|  |