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

[Akira Yokosawa]

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@xxxxxxxxx>
> Signed-off-by: Alex Gaynor <alex.gaynor@xxxxxxxxx>
> Co-developed-by: Finn Behrens <me@xxxxxxxxx>
> Signed-off-by: Finn Behrens <me@xxxxxxxxx>
> Co-developed-by: Adam Bratschi-Kaye <ark.email@xxxxxxxxx>
> Signed-off-by: Adam Bratschi-Kaye <ark.email@xxxxxxxxx>
> Co-developed-by: Wedson Almeida Filho <wedsonaf@xxxxxxxxxx>
> Signed-off-by: Wedson Almeida Filho <wedsonaf@xxxxxxxxxx>
> Co-developed-by: Michael Ellerman <mpe@xxxxxxxxxxxxxx>
> Signed-off-by: Michael Ellerman <mpe@xxxxxxxxxxxxxx>
> Co-developed-by: Sven Van Asbroeck <thesven73@xxxxxxxxx>
> Signed-off-by: Sven Van Asbroeck <thesven73@xxxxxxxxx>
> Co-developed-by: Wu XiangCheng <bobwxc@xxxxxxxx>
> Signed-off-by: Wu XiangCheng <bobwxc@xxxxxxxx>
> Co-developed-by: Gary Guo <gary@xxxxxxxxxxx>
> Signed-off-by: Gary Guo <gary@xxxxxxxxxxx>
> Co-developed-by: Boris-Chengbiao Zhou <bobo1239@xxxxxx>
> Signed-off-by: Boris-Chengbiao Zhou <bobo1239@xxxxxx>
> Co-developed-by: Yuki Okushi <jtitor@xxxxxxxx>
> Signed-off-by: Yuki Okushi <jtitor@xxxxxxxx>
> Co-developed-by: Wei Liu <wei.liu@xxxxxxxxxx>
> Signed-off-by: Wei Liu <wei.liu@xxxxxxxxxx>
> Co-developed-by: Daniel Xu <dxu@xxxxxxxxx>
> Signed-off-by: Daniel Xu <dxu@xxxxxxxxx>
> Co-developed-by: Julian Merkle <me@xxxxxxxxxxx>
> Signed-off-by: Julian Merkle <me@xxxxxxxxxxx>
> Signed-off-by: Miguel Ojeda <ojeda@xxxxxxxxxx>
> ---
>  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@xxxxxxxxxxxxxx/

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