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

Gary Guo
2026-05-05T00:25:48Z

On Tue May 5, 2026 at 12:23 AM BST, Mauro Carvalho Chehab wrote:
> On Mon, 04 May 2026 23:37:38 +0100
> "Gary Guo" <gary@garyguo.net> wrote:
>
>> On Mon May 4, 2026 at 9:26 PM BST, Mauro Carvalho Chehab wrote:
>> > On Mon, 4 May 2026 18:08:06 +0200
>> > Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
>> >
>> >> On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
>> >> <mchehab+huawei@kernel.org> wrote:
>> >> >
>> >> > Currently, there is a "P" entry for Rust pin-point that is
>>
>> I suppose the commit message is supposed to refer to pin-init instead of
>> pin-point?
>
> Gah, sorry for the typo!
>
> I'll fix on a next version.
>
>> >> > neither a valid ReST file nor an hyperlink. While the real
>> >>
>> >> I guess you mean pin-init above, i.e. this entry:
>> >>
>> >> P: rust/pin-init/CONTRIBUTING.md
>> >>
>> >> It would be nice to clarify it in the commit message that it refers to
>> >> a file (which is allowed for `P:` entries according to the docs).
>> >
>> > It is not written there, but by file, it would actually be expected
>> > a file within Documentation in ReST format ;-)
>> >
>> >> And, yeah, ideally we could make it a hyperlink to the raw file.
>> >
>> > 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).
>>
>> I suppose we can just change it to a link to the render doc on GitHub.
>
> This works too: there are other P: entries like that pointing to an
> external URL that was rendered somehow.
>
> That's said, GitHub (and, AFAIKT GitLab) supports both Markdown and
> ReStructured Text. So, if one wants to keep the file on both places,
> rst is a common denominator.

Unfortunately that'll create some internal inconsistency for pin-init as we'd
have a CONTRIBUTING.rst next to a README.md. The README has to have markdown
format as we have some code samples that's shared with Rust crate documentation
which needs to be Markdown.

Doing conversions could work, but it feels too much hassle for a single P: entry
so I'd rather just change it to the external link. (Also it'll have a chance of
getting out of sync, especially if conversions are not loseless and they cannot
round-trip, which I suppose is likely).

Best,
Gary