Re: [PATCH] kernel-doc: better handle '::' sequences

[Miguel Ojeda]

On Tue, Mar 30, 2021 at 1:07 PM Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote:
>
> FWIW, and this should be obvious, I think going with what's natural for
> documenting Rust source code is the right choice. Markdown as parsed by
> rustdoc. People will expect Rust documentation comments to just work,
> without some kernel specific gotchas. Don't try to reinvent the wheel
> here, it's a dead end.

Agreed!

> The interesting question is, I think, figuring out if rustdoc output
> could be incorporated into Sphinx documentation, and how. It would be
> pretty disappointing if we ended up with two documentation silos based
> on the module implementation language.

I want to have the Rust docs linked from Sphinx and uploaded as usual
to kernel.org etc.

However, please note that the implementation language implies a lot of
things, not just the "implementation language", if that makes sense.

For instance, if you write your module in Rust, the idea is that you
use the Rust infrastructure and exposed abstractions -- not that you
call C kernel functions on your own.

> At the moment it seems to me rustdoc can only output HTML, and that
> seems pretty deeply ingrained in the tool. AFAICT, there isn't an
> intermediate phase where it would be trivial to output the documentation
> in Markdown (though I don't really know Rust and I only had a cursory
> look at librustdoc). And even if it were possible, with Markdown you'd
> have the issues with conflicting Markdown flavours, what's supported by
> rustdoc vs. commonmark.py used by Sphinx.

Please note that `rustdoc` generates HTML that is intended for Rust
code, i.e. generating an intermediate format to then generate HTML
from Sphinx would make the Rust docs worse, unless the mapping is
perfect (but, at that point, why not just keep the standard Rust
docs?).

> Perhaps the bare minimum is running rustdoc first, and generating the
> results into Sphinx static pages [1], to make them part of the
> whole. Even if the HTML style might be different. Perhaps it would be

I don't think it is the "bare minimum", I think this is the optimal
solution! :-)

It is also not just about the style. The Rust docs are organized for
Rust code, the search functionality is meant for it, etc.

> possible to come up with a Sphinx extensions to make it convenient to
> reference content in the rustdoc generated HTML from reStructuredText.

For C -> Rust links, the plan I suggested to Jonathan was to have
Sphinx generate a text file with (reference, URL) pairs that then
`rustdoc` can use as links (e.g. to link to, say, the docs for
`printk`).

I also discussed it with the `rustdoc` maintainers, and they thought
it would be an interesting proposal, so I agreed to make an RFC for it
(note that it can be useful not just for Rust docs that need to refer
to C code, but also for any other kind of external content, e.g.
imagine a math library referencing a set of papers, books, etc.
without having to re-write the URL everywhere).

Cheers,
Miguel