[PATCH 0/2] Table of contents refactoring for tracing docs

[PATCH 0/2] Table of contents refactoring for tracing docs

[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. The patch diffs are left intact but I reword
the patch descriptions.

Enjoy!

[1]: https://lore.kernel.org/linux-doc/20250318113230.24950-1-purvayeshi550@gmail.com/T/#u

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

 Documentation/trace/index.rst | 96 +++++++++++++++++++++++++++++------
 1 file changed, 80 insertions(+), 16 deletions(-)


base-commit: 43e9076a00b17cf8115b4bd4d3b2be33a44245ca
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/2] Documentation: trace: Reduce toctree depth

[Bagas Sanjaya]

From: Purva Yeshi <purvayeshi550@gmail.com>

Reduce toctree depth from 2 to 1 so that only docs titles are listed
in the toctree. Individual docs' table of contents can be shown on
sidebar by actually visiting the respective docs.

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Link: https://lore.kernel.org/r/20250318113230.24950-1-purvayeshi550@gmail.com
[Bagas: massage commit message]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 2c991dc96ace60..fecc4adf70a830 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -3,7 +3,7 @@ Linux Tracing Technologies
 ==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ftrace-design
    tracepoint-analysis
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/2] Documentation: trace: Refactor toctree

[Bagas Sanjaya]

From: Purva Yeshi <purvayeshi550@gmail.com>

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

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Link: https://lore.kernel.org/r/20250318113230.24950-2-purvayeshi550@gmail.com
[Bagas: massage commit message]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---

Hi Steven,

I remove your Acked-by: since I massage the patch description. Would you mind
to re-add yours?

Thanks.

 Documentation/trace/index.rst | 94 +++++++++++++++++++++++++++++------
 1 file changed, 79 insertions(+), 15 deletions(-)

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index fecc4adf70a830..5ddd47ee781211 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -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
+
+Additional Resources
+--------------------
+
+For more details, refer to the respective documentation of each
+tracing tool and framework.
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
\ No newline at end of file
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 2/2] Documentation: trace: Refactor toctree

[Steven Rostedt]

On Tue, 15 Apr 2025 10:46:13 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> 
> Hi Steven,
> 
> I remove your Acked-by: since I massage the patch description. Would you mind
> to re-add yours?

Sure, I do have one comment below.

> 
> Thanks.
> 
>  Documentation/trace/index.rst | 94 +++++++++++++++++++++++++++++------
>  1 file changed, 79 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index fecc4adf70a830..5ddd47ee781211 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -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

I think the uprobetracer can go into the user space tracing below.
As uprobes attaches to user space programs.

>     fprobetrace
> -   tracepoints
> +   fprobe
> +   ring-buffer-design
> +

[..]

> +
> +User-Space Tracing
> +------------------
> +
> +These tools allow tracing user-space applications and
> +interactions.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   user_events

      uprobetracer

-- Steve


> +
> +Additional Resources
> +--------------------
> +
> +For more details, refer to the respective documentation of each
> +tracing tool and framework.
> +
> +.. only:: subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> \ No newline at end of file

Re: [PATCH 2/2] Documentation: trace: Refactor toctree

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1003 bytes --]

On Tue, Apr 15, 2025 at 10:06:17AM -0400, Steven Rostedt wrote:
> > +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
> 
> I think the uprobetracer can go into the user space tracing below.
> As uprobes attaches to user space programs.
> 
> >     fprobetrace
> > -   tracepoints
> > +   fprobe
> > +   ring-buffer-design
> > +
> 
> [..]
> 
> > +
> > +User-Space Tracing
> > +------------------
> > +
> > +These tools allow tracing user-space applications and
> > +interactions.
> > +
> > +.. toctree::
> > +   :maxdepth: 1
> > +
> > +   user_events
> 
>       uprobetracer
> 

Will be addressed in v2.

Thanks.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]