Re: [PATCH v2 11/11] MAINTAINERS: use a URL for pin-init maintainer's profile entry

[Miguel Ojeda]

On Wed, May 6, 2026 at 8:49 AM Mauro Carvalho Chehab
<mchehab+huawei@xxxxxxxxxx> wrote:
>
> Maybe it is just me, but placing doc files in the crowd together with code
> on a project where documentation has its own directory sounds weird(*).
>
> (*) except for userspace tools and staging drivers where we want
>     everything, including documentation, contained on a single place.

It is a similar case -- they are vendored libraries developed and used
elsewhere (e.g. in userspace too).

> As you're already using some scripting to do a bidirectional sync,
> you could add there some logic to convert rust pin-init documentation
> to rst and place it at Documentation/rust/.

Most of the pin-init documentation is elsewhere (embedded in the Rust
source code) and already rendered at rust.docs.kernel.org.

(Using Sphinx for Rust has been discussed in the list a few times in
the past too, and that has its own set of constraints).

> Btw, on a quick check, only Rust has markdown files:
>
>         $ git ls-files|grep ".md$"|grep -v tools/
>         rust/pin-init/CONTRIBUTING.md
>         rust/pin-init/README.md
>         rust/proc-macro2/README.md
>         rust/quote/README.md
>         rust/syn/README.md
>
> As one of the people who spent years helping improving the Kernel
> documentation and doing lots of conversions from markdown
> and other non-structured text formats to RST, I have to say that I'm
> concerned with any trends that would add doc files that aren't
> properly integrated with the Kernel documentation system like those.

All those are vendored libraries, and most of those `README.md` files
are about clarifying where they are taken from and their licensing,
e.g.

    # `quote`

    These source files come from the Rust `quote` crate, version 1.0.40
    (released 2025-03-12), hosted in the <https://github.com/dtolnay/quote>
    repository, licensed under "Apache-2.0 OR MIT" and only modified to add
    the SPDX license identifiers.

    For copyright details, please see:

        https://github.com/dtolnay/quote/blob/1.0.40/README.md#license
        https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-APACHE
        https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-MIT

i.e. they are not intended to be kernel documentation, and moving them
away from the source files doesn't sound like an improvement,
especially since we were explicitly requested to make the provenance
very clear.

We could perhaps have a list of vendored libraries in
Documentation/rust/vendored-libraries.rst` -- that could perhaps be
useful for some folks.

In any case, I understand your desire to keep things integrated in the
kernel documentation, and I appreciate that (I also like to have
everything neatly integrated), but please do not assume we have been
randomly adding Markdown for no reason or that we are not trying to
keep things properly integrated... :(

Cheers,
Miguel