Re: [PATCH v6 18/23] docs: add Rust documentation

Akira Yokosawa
2022-05-09T04:09:12Z

Hi Miguel,

On Sat, 7 May 2022 07:24:16 +0200,
Miguel Ojeda wrote:
> Most of the documentation for Rust is written within the source code
> itself, as it is idiomatic for Rust projects. This applies to both
> the shared infrastructure at `rust/` as well as any other Rust module
> (e.g. drivers) written across the kernel.
>
> However, these documents contain general information that does not
> fit particularly well in the source code, like the Quick Start guide.
>
> It also contains an asset (SVG logo) used for the `rustdoc` target
> and a few other small changes elsewhere in the documentation folder.
>
> Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com>
> Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com>
> Co-developed-by: Finn Behrens <me@kloenk.de>
> Signed-off-by: Finn Behrens <me@kloenk.de>
> Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com>
> Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com>
> Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com>
> Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com>
> Co-developed-by: Michael Ellerman <mpe@ellerman.id.au>
> Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
> Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com>
> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>
> Co-developed-by: Wu XiangCheng <bobwxc@email.cn>
> Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
> Co-developed-by: Gary Guo <gary@garyguo.net>
> Signed-off-by: Gary Guo <gary@garyguo.net>
> Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de>
> Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de>
> Co-developed-by: Yuki Okushi <jtitor@2k36.org>
> Signed-off-by: Yuki Okushi <jtitor@2k36.org>
> Co-developed-by: Wei Liu <wei.liu@kernel.org>
> Signed-off-by: Wei Liu <wei.liu@kernel.org>
> Co-developed-by: Daniel Xu <dxu@dxuuu.xyz>
> Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
> Co-developed-by: Julian Merkle <me@jvmerkle.de>
> Signed-off-by: Julian Merkle <me@jvmerkle.de>
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> Documentation/doc-guide/kernel-doc.rst | 3 +
> Documentation/index.rst | 1 +
> Documentation/kbuild/kbuild.rst | 17 +
> Documentation/kbuild/makefiles.rst | 50 ++-
> Documentation/process/changes.rst | 41 +++
> Documentation/rust/arch-support.rst | 34 ++
> Documentation/rust/coding-guidelines.rst | 214 ++++++++++++
> Documentation/rust/general-information.rst | 77 +++++
> Documentation/rust/index.rst | 20 ++
> Documentation/rust/logo.svg | 357 +++++++++++++++++++++
I think you agreed splitting SVG part into its own patch with
a proper copying info, etc. Let me see... So, here is the link:

https://lore.kernel.org/lkml/CANiq72mLtvWJ5peSTpYQ8AeLEskga6Pda8Q7Daysv2pfycnyxA@mail.gmail.com/

I might have missed v5 of this patch series.
That might be because v5's 15/20 was not accepted by linux-doc's
lore archive (maybe) due to its size despite it had Cc: linux-doc.
v6's 18/23 was also rejected.

> Documentation/rust/quick-start.rst | 230 +++++++++++++
> 11 files changed, 1040 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/rust/arch-support.rst
> create mode 100644 Documentation/rust/coding-guidelines.rst
> create mode 100644 Documentation/rust/general-information.rst
> create mode 100644 Documentation/rust/index.rst
> create mode 100644 Documentation/rust/logo.svg
> create mode 100644 Documentation/rust/quick-start.rst

I have some alternative ideas for table formatting in ReST.

> diff --git a/Documentation/rust/arch-support.rst b/Documentation/rust/arch-support.rst
> new file mode 100644
> index 000000000000..482757a1f3d0
> --- /dev/null
> +++ b/Documentation/rust/arch-support.rst
> @@ -0,0 +1,34 @@
> +Arch Support
> +============
> +
> +Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
> +which limits the supported architectures that can be targeted. In addition,
> +support for building the kernel with LLVM/Clang varies (please see
> +Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
> +which uses ``libclang``.
> +
> +Below is a general summary of architectures that currently work. Level of
> +support corresponds to ``S`` values in the ``MAINTAINERS`` file.
> +
> +.. list-table::
> + :widths: 10 10 10
> + :header-rows: 1
> +
> + * - Architecture
> + - Level of support
> + - Constraints
> + * - ``arm``
> + - Maintained
> + - ``armv6`` and compatible only, ``RUST_OPT_LEVEL >= 2``
> + * - ``arm64``
> + - Maintained
> + - None
> + * - ``powerpc``
> + - Maintained
> + - ``ppc64le`` only, ``RUST_OPT_LEVEL < 2`` requires ``CONFIG_THREAD_SHIFT=15``
> + * - ``riscv``
> + - Maintained
> + - ``riscv64`` only
> + * - ``x86``
> + - Maintained
> + - ``x86_64`` only

Excerpt from Section "list tables" in
Documentation/doc-guide/sphinx.rst:

> The list-table formats can be useful for tables that are not easily laid
> out in the usual Sphinx ASCII-art formats. These formats are nearly
> impossible for readers of the plain-text documents to understand, though,
> and should be avoided in the absence of a strong justification for their
> use.

So here are a couple of alternative ways to represent the table

* ASCII-art format:

============ ================ ==========================================
Architecture Level of support Constraints
============ ================ ==========================================
``arm`` Maintained ``armv6`` and compatible only,
``RUST_OPT_LEVEL >= 2``
``arm64`` Maintained None
``powerpc`` Maintained ``ppc64le`` only, ``RUST_OPT_LEVEL < 2``
requires ``CONFIG_THREAD_SHIFT=15``
``riscv`` Maintained ``riscv64`` only
``x86`` Maintained ``x86_64`` only
============ ================ ==========================================

* Literal block format:

::

Architecture Level of support Constraints
------------ ---------------- -------------------------------------
arm Maintained armv6 and compatible only,
RUST_OPT_LEVEL >= 2
arm64 Maintained None
powerpc Maintained ppc64le only, RUST_OPT_LEVEL < 2
requires CONFIG_THREAD_SHIFT=15
riscv Maintained riscv64 only
x86 Maintained x86_64 only

"::" above the table marks the start of a literal block.
Indents are important for la iteral block to work.
A literal block ends at a line which has the same indent as
the preceding paragraph, in this case with no indent, or at
the end of file.

As you see, those inline-literal markers of ``xxxx``, which are
distracting when the .rst file is read as plain-text, are not
necessary in the literal-block approach. And you can directly
tweak line breaks in the Constraints column in the final HTML
and PDF docs.

In my opinion, the literal-block approach should be the most
reasonable choice here. Of course its your call which one
to choose.

Thanks, Akira