Re: [PATCH v2] docs: dt: Make references and mention kernel abstractions

[Bagas Sanjaya]

On Sat, May 06, 2023 at 03:09:11PM -0700, Randy Dunlap wrote:
> For @linux-doc: Is there something in ReST that does auto section numbering
> so that this renumbering does not have to be repeated in the future?
> 

There is sectnum:: directive which does the job. In the kernel docs,
however, it is customarily used together with contents:: directive to
generate toctree for current doc. In order for this to work as expected,
you need also to rearrange section heading levels, like:

---- >8 ----
diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 87f522d5feba81..890dde293540f9 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -1,5 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. contents::
+.. sectnum::
+
 ========================
 Linux and the Devicetree
 ========================
@@ -76,7 +79,7 @@ If you haven't already read the Device Tree Usage\ [1]_ page,
 then go read it now.  It's okay, I'll wait....
 
 2.1 Linux Kernel Firmware Abstractions
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
@@ -112,7 +115,8 @@ resources to other devices in the DT, will need to implement calls into
 the DT abstractions.
 
 2.2 High Level View
--------------------
+~~~~~~~~~~~~~~~~~~~
+
 The most important thing to understand is that the DT is simply a data
 structure that describes the hardware.  There is nothing magical about
 it, and it doesn't magically make all hardware configuration problems
@@ -134,7 +138,8 @@ Linux uses DT data for three major purposes:
 3) device population.
 
 2.3 Platform Identification
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 First and foremost, the kernel will use data in the DT to identify the
 specific machine.  In a perfect world, the specific platform shouldn't
 matter to the kernel because all platform details would be described
@@ -217,7 +222,8 @@ compatible list, and probably should be avoided for new architecture
 support.
 
 2.4 Runtime configuration
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In most cases, a DT will be the sole method of communicating data from
 firmware to the kernel, so also gets used to pass in runtime and
 configuration data like the kernel parameters string and the location
@@ -254,7 +260,8 @@ scanning of the device tree after selecting the correct machine_desc
 that supports the board.
 
 2.5 Device population
----------------------
+~~~~~~~~~~~~~~~~~~~~~
+
 After the board has been identified, and after the early configuration data
 has been parsed, then kernel initialization can proceed in the normal
 way.  At some point in this process, unflatten_device_tree() is called

The caveat is the title heading also get numbered, making it top-level
section. Hence, it is more appropriate if the directory toctree:: also
have :numbered: option to do the job instead:

---- >8 ----
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 1a2fc80149966e..b5297dd511ef31 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -8,6 +8,7 @@ Kernel Devicetree Usage
 =======================
 .. toctree::
    :maxdepth: 1
+   :numbered:
 
    usage-model
    of_unittest

Anyway, if you use auto section numbering, you need to also remove the manual
numbers:

---- >8 ----
diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 0ff62cdb3cc51c..e2dfbcc38c2f03 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -42,8 +42,8 @@ incompatible, bindings for i2c busses that came about because the new
 binding was created without first investigating how i2c devices were
 already being enumerated in existing systems.
 
-1. History
-----------
+History
+-------
 The DT was originally created by Open Firmware as part of the
 communication method for passing data from Open Firmware to a client
 program (like to an operating system).  An operating system used the
@@ -72,13 +72,13 @@ all architectures.  At the time of this writing, 6 mainlined
 architectures (arm, microblaze, mips, powerpc, sparc, and x86) and 1
 out of mainline (nios) have some level of DT support.
 
-2. Data Model
--------------
+Data Model
+----------
 If you haven't already read the Device Tree Usage\ [1]_ page,
 then go read it now.  It's okay, I'll wait....
 
-2.1 Linux Kernel Firmware Abstractions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Linux Kernel Firmware Abstractions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
@@ -113,8 +113,8 @@ detected devices using the device tree, or that want to provide
 resources to other devices in the DT, will need to implement calls into
 the DT abstractions.
 
-2.2 High Level View
-~~~~~~~~~~~~~~~~~~~
+High Level View
+~~~~~~~~~~~~~~~
 
 The most important thing to understand is that the DT is simply a data
 structure that describes the hardware.  There is nothing magical about
@@ -136,8 +136,8 @@ Linux uses DT data for three major purposes:
 2) runtime configuration, and
 3) device population.
 
-2.3 Platform Identification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Platform Identification
+~~~~~~~~~~~~~~~~~~~~~~~
 
 First and foremost, the kernel will use data in the DT to identify the
 specific machine.  In a perfect world, the specific platform shouldn't
@@ -220,8 +220,8 @@ However, this approach does not take into account the priority of the
 compatible list, and probably should be avoided for new architecture
 support.
 
-2.4 Runtime configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Runtime configuration
+~~~~~~~~~~~~~~~~~~~~~
 
 In most cases, a DT will be the sole method of communicating data from
 firmware to the kernel, so also gets used to pass in runtime and
@@ -258,8 +258,8 @@ On ARM, the function setup_machine_fdt() is responsible for early
 scanning of the device tree after selecting the correct machine_desc
 that supports the board.
 
-2.5 Device population
-~~~~~~~~~~~~~~~~~~~~~
+Device population
+~~~~~~~~~~~~~~~~~
 
 After the board has been identified, and after the early configuration data
 has been parsed, then kernel initialization can proceed in the normal

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature