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