Skip to contentSkip to conversation

Table of contents refactoring for tracing docs

PATCH Applied Bagas Sanjaya 3 participants 5 messages Apr 16, 2025 – Apr 21, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

v2 cover Table of contents refactoring for tracing docs

Hi,

The trace toctree refactoring series [1] didn't make it through 6.15 merge window previously, so I forwarded it targeting 6.16 via docs-next tree instead.

Enjoy!

Changes since v1 [2]:

- Remove mention of individual docs' toctree as the generated sidebar toctree don't include them ([patch 1/2])
- Move uprobetracer to user-space tracing section (Steven, [patch 2/2])

[1]: https://lore.kernel.org/linux-doc/[email protected]/T/#u
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Purva Yeshi (2):
Documentation: trace: Reduce toctree depth
Documentation: trace: Refactor toctree

 Documentation/trace/index.rst | 98 +++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 17 deletions(-)

base-commit: 43e9076a00b17cf8115b4bd4d3b2be33a44245ca

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH v2 1/2 Documentation: trace: Reduce toctree depth

From: Purva Yeshi <[email protected]>

Reduce toctree depth from 2 to 1 so that only docs titles are listed in the toctree.

---
 Documentation/trace/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/trace/index.rst +1 -1
index 2c991dc96ace60..fecc4adf70a830 100644
@@ -3,7 +3,7 @@ Linux Tracing Technologies
 ==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ftrace-design
    tracepoint-analysis
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

PATCH v2 2/2 Documentation: trace: Refactor toctree

In reply to Bagas Sanjaya

From: Purva Yeshi <[email protected]>

Refactor table of contents of kernel tracing subsystem docs to improve clarity, structure, and organization:

- Reformat sections and add appropriate headings
- Improve section grouping and refine descriptions for each group
- Add docs intro paragraph

---
 Documentation/trace/index.rst | 96 +++++++++++++++++++++++++++++------
 1 file changed, 80 insertions(+), 16 deletions(-)
Documentation/trace/index.rst +80 -16
index fecc4adf70a830..cc1dc5a087e8b1 100644
@@ -1,39 +1,103 @@
-==========================
-Linux Tracing Technologies
-==========================
+================================
+Linux Tracing Technologies Guide
+================================
+
+Tracing in the Linux kernel is a powerful mechanism that allows
+developers and system administrators to analyze and debug system
+behavior. This guide provides documentation on various tracing
+frameworks and tools available in the Linux kernel.
+
+Introduction to Tracing
+-----------------------
+
+This section provides an overview of Linux tracing mechanisms
+and debugging approaches.
 
 .. toctree::
    :maxdepth: 1
 
-   ftrace-design
+   debugging
+   tracepoints
    tracepoint-analysis
+   ring-buffer-map
+
+Core Tracing Frameworks
+-----------------------
+
+The following are the primary tracing frameworks integrated into
+the Linux kernel.
+
+.. toctree::
+   :maxdepth: 1
+
    ftrace
+   ftrace-design
    ftrace-uses
-   fprobe
    kprobes
    kprobetrace
-   uprobetracer
    fprobetrace
-   tracepoints
+   fprobe
+   ring-buffer-design
+
+Event Tracing and Analysis
+--------------------------
+
+A detailed explanation of event tracing mechanisms and their
+applications.
+
+.. toctree::
+   :maxdepth: 1
+
    events
    events-kmem
    events-power
    events-nmi
    events-msr
-   mmiotrace
+   boottime-trace
    histogram
    histogram-design
-   boottime-trace
-   debugging
-   hwlat_detector
-   osnoise-tracer
-   timerlat-tracer
+
+Hardware and Performance Tracing
+--------------------------------
+
+This section covers tracing features that monitor hardware
+interactions and system performance.
+
+.. toctree::
+   :maxdepth: 1
+
    intel_th
-   ring-buffer-design
-   ring-buffer-map
    stm
    sys-t
    coresight/index
-   user_events
    rv/index
    hisi-ptt
+   mmiotrace
+   hwlat_detector
+   osnoise-tracer
+   timerlat-tracer
+
+User-Space Tracing
+------------------
+
+These tools allow tracing user-space applications and
+interactions.
+
+.. toctree::
+   :maxdepth: 1
+
+   user_events
+   uprobetracer
+
+Additional Resources
+--------------------
+
+For more details, refer to the respective documentation of each
+tracing tool and framework.
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer Acked-by on the v2 series
#3 lore raw
In reply to Bagas Sanjaya
Quoted 17 lines · On Wed, 16 Apr 2025 09:40:48 +0700 Bagas Sanjaya <[email protected]> wrote:

Hi,

The trace toctree refactoring series [1] didn't make it through 6.15 merge window previously, so I forwarded it targeting 6.16 via docs-next tree instead.

Enjoy!

Changes since v1 [2]:

- Remove mention of individual docs' toctree as the generated sidebar toctree don't include them ([patch 1/2])
- Move uprobetracer to user-space tracing section (Steven, [patch 2/2])

[1]: https://lore.kernel.org/linux-doc/[email protected]/T/#u
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Quoted 6 lines

Purva Yeshi (2):
Documentation: trace: Reduce toctree depth
Documentation: trace: Refactor toctree

 Documentation/trace/index.rst | 98 +++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 17 deletions(-)

for both patches.

Jon, feel free to take this through your tree.

Thanks,

-- Steve

maintainer Applied
#4 lore raw
In reply to Bagas Sanjaya
Quoted 17 lines · Bagas Sanjaya

Hi,

The trace toctree refactoring series [1] didn't make it through 6.15 merge window previously, so I forwarded it targeting 6.16 via docs-next tree instead.

Enjoy!

Changes since v1 [2]:

- Remove mention of individual docs' toctree as the generated sidebar toctree don't include them ([patch 1/2])
- Move uprobetracer to user-space tracing section (Steven, [patch 2/2])

[1]: https://lore.kernel.org/linux-doc/[email protected]/T/#u
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Quoted 6 lines

Purva Yeshi (2):
Documentation: trace: Reduce toctree depth
Documentation: trace: Refactor toctree

 Documentation/trace/index.rst | 98 +++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 17 deletions(-)

Applied, thanks.

jon