[Dropped most CCs] Hi Miguel. I have a follow-up hint on cross referencing for you. See below. On Mon, 14 Feb 2022 19:47:36 +0900, Akira Yokosawa wrote: > Hi, > > Please find inline comments WRT ReST-in-kereneldoc. > > Jon, if I'm missing something, please enlighten me. > > On Sat, 12 Feb 2022 14:03:41 +0100, > Miguel Ojeda <ojeda@xxxxxxxxxx> wrote: [...] >> diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst >> new file mode 100644 >> index 000000000000..9ee4c6994d08 >> --- /dev/null >> +++ b/Documentation/rust/general-information.rst >> @@ -0,0 +1,80 @@ >> +.. _rust_general_information: > Unnecessary tag. > >> + >> +General Information >> +=================== >> + >> +This document contains useful information to know when working with >> +the Rust support in the kernel. >> + >> + >> +Code documentation >> +------------------ >> + >> +Rust kernel code is documented using ``rustdoc``, its built-in documentation >> +generator. >> + >> +The generated HTML docs include integrated search, linked items (e.g. types, >> +functions, constants), source code, etc. They may be read at (TODO: link when >> +in mainline and generated alongside the rest of the documentation): >> + >> + http://kernel.org/ >> + >> +The docs can also be easily generated and read locally. This is quite fast >> +(same order as compiling the code itself) and no special tools or environment >> +are needed. This has the added advantage that they will be tailored to >> +the particular kernel configuration used. To generate them, use the ``rustdoc`` >> +target with the same invocation used for compilation, e.g.:: >> + >> + make LLVM=1 rustdoc >> + >> +To read the docs locally in your web browser, run e.g.:: >> + >> + xdg-open rust/doc/kernel/index.html >> + >> +To learn about how to write the documentation, please see the coding guidelines >> +at :ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`. > at Documentation/rust/coding-guidelines.rst. Here, the cross reference is internal to Documentation/rust/. In this case, a relative path works for both top and subdirectory level build. So you can say: at coding-guidelines.rst. > >> + >> + >> +Extra lints >> +----------- >> + >> +While ``rustc`` is a very helpful compiler, some extra lints and analyses are >> +available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to >> +the same invocation used for compilation, e.g.:: >> + >> + make LLVM=1 CLIPPY=1 >> + >> +Please note that Clippy may change code generation, thus it should not be >> +enabled while building a production kernel. >> + >> + >> +Abstractions vs. bindings >> +------------------------- >> + >> +Abstractions are Rust code wrapping kernel functionality from the C side. >> + >> +In order to use functions and types from the C side, bindings are created. >> +Bindings are the declarations for Rust of those functions and types from >> +the C side. >> + >> +For instance, one may write a ``Mutex`` abstraction in Rust which wraps >> +a ``struct mutex`` from the C side and calls its functions through the bindings. >> + >> +Abstractions are not available for all the kernel internal APIs and concepts, >> +but it is intended that coverage is expanded as time goes on. "Leaf" modules >> +(e.g. drivers) should not use the C bindings directly. Instead, subsystems >> +should provide as-safe-as-possible abstractions as needed. >> + >> + >> +Conditional compilation >> +----------------------- >> + >> +Rust code has access to conditional compilation based on the kernel >> +configuration: >> + >> +.. code-block:: rust >> + >> + #[cfg(CONFIG_X)] // Enabled (`y` or `m`) >> + #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) >> + #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) >> + #[cfg(not(CONFIG_X))] // Disabled >> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst >> new file mode 100644 >> index 000000000000..6e20af5b723a >> --- /dev/null >> +++ b/Documentation/rust/index.rst >> @@ -0,0 +1,21 @@ >> +Rust >> +==== >> + >> +Documentation related to Rust within the kernel. To start using Rust >> +in the kernel, please read the >> +:ref:`Documentation/rust/quick-start.rst <rust_quick_start>` guide. > in the kernel, please read the guide in Documentation/rust/quick-start.rst. in the kernel, please read the guide in quick-start.rst. , and so on. Thanks, Akira [...] > > > Notes: > > Those cross-references of plain path such as > > Documentation/rust/general-information.rst > > are recognized when you build by the top level "make htmldocs". > If you specify a subdirectory by "make SPHINXDIRS=rust htmldocs", > current build script can't recognize them. This is one of (not > widely recognized) issues in subdirectory handling of automarkup.py. > Hopefully, they can be resolved soon. > > Tags at the top of .rst files are redundant and should be avoided. > Existing ones can be removed after referencing sites are updated. > > Thanks, Akira
