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
