Re: [PATCH v4 15/20] docs: add Rust documentation

[Akira Yokosawa <akiyks@gmail.com>]

[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@kernel.org> 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