Date:   Tue, 30 Mar 2021 14:07:14 +0300
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Miguel Ojeda <miguel.ojeda.sandonis@...il.com>,
        Matthew Wilcox <willy@...radead.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Rob Herring <robh@...nel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] kernel-doc: better handle '::' sequences

On Mon, 29 Mar 2021, Miguel Ojeda <miguel.ojeda.sandonis@...il.com> wrote:
> On Thu, Mar 25, 2021 at 11:18 PM Matthew Wilcox <willy@...radead.org> wrote:
>>
>> The rust code is alredy coming though ...
>>
>> rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
>>
>> so now we have three formats.  Markdown and RST are _very_ similar, but
>> not identical [1].  Oh, and even better we now have three distinct tools --
>> kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
>> about integrating the various docs?
>
> Yeah, I reached out to Jonathan a few weeks ago to discuss how we will
> approach this, because I knew using `rustdoc` and Markdown could be
> contentious ;-)
>
> This is the solution we decided to go for the RFC but, of course,
> nothing is set in stone:
>
>   1. The "out-of-line" docs in `Documentation/rust/`: these will be in
> RST as usual [*]. However, please note this does not include APIs or
> anything like that, as it is done in the C side. Only a few "general
> documents" that don't fit anywhere else are kept here.
>
>   2. The "inline" docs in Rust source files: these will be parsed by
> `rustdoc` and written in Markdown. These will contain the majority of
> the Rust documentation. `rustdoc` is designed for Rust code, and
> internally uses the Rust compiler, which comes with a number of
> advantages.
>
> The generated HTML docs will be showcased in the RFC. It is my hope
> that this way we get feedback on them and see if people agree this
> approach is worth keeping. We have put an effort (and I have been
> annoying contributors enough to that end :-) to provide high-quality
> documentation from the get-go.
>
> Please note that we chose this way knowing well that inconsistency and
> adding "yet one more tool" needs to come with big advantages to
> offset. We think it is the best approach nevertheless!
>
> [*] I discussed with Jonathan using Markdown since Sphinx supports it.
> The main advantage would be easier refactoring of comments between the
> out- and inline docs. But this is very minor, thus mixing two formats
> inside `Documentation/` does not seem like worth it.

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.

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.

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.

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
possible to come up with a Sphinx extensions to make it convenient to
reference content in the rustdoc generated HTML from reStructuredText.


BR,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path


-- 
Jani Nikula, Intel Open Source Graphics Center

Powered by blists - more mailing lists