[PATCH v4 1/2] docs: tracing: Reduce maxdepth in index.rst for clarity

[PATCH v4 1/2] docs: tracing: Reduce maxdepth in index.rst for clarity

[Purva Yeshi]

Reduce :maxdepth: from 2 to 1 in index.rst to simplify the table of
contents, showing only top-level document titles for better readability.

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
---
V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@gmail.com/
V2 - https://lore.kernel.org/lkml/20250206141453.139613-1-purvayeshi550@gmail.com/
V3 - https://lore.kernel.org/all/20250312124717.7208-1-purvayeshi550@gmail.com/
V4 - Reorder patches to apply the 'maxdepth' change first, then refactor
the index documentation to avoid introducing maxdepth: 2 only to modify
it in the next patch.

 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 2c991dc96..fecc4adf7 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
-- 
2.34.1

[PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

[Purva Yeshi]

Refactor Documentation/trace/index.rst to improve clarity, structure,
and organization. Reformat sections and add appropriate headings for
better readability.

Improve section grouping and refine descriptions for better usability.

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
---
 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 fecc4adf7..5ddd47ee7 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
-- 
2.34.1

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

[Bagas Sanjaya]

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

On Tue, Mar 18, 2025 at 05:02:30PM +0530, Purva Yeshi wrote:
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index fecc4adf7..5ddd47ee7 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

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

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

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

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

[Steven Rostedt]

On Tue, 18 Mar 2025 17:02:30 +0530
Purva Yeshi <purvayeshi550@gmail.com> wrote:

> Refactor Documentation/trace/index.rst to improve clarity, structure,
> and organization. Reformat sections and add appropriate headings for
> better readability.
> 
> Improve section grouping and refine descriptions for better usability.
> 
> Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
> ---
>  Documentation/trace/index.rst | 94 +++++++++++++++++++++++++++++------
>  1 file changed, 79 insertions(+), 15 deletions(-)

For both patches:

 Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org.

Jon,

Feel free to apply these to your tree.

Thanks,

-- Steve

Re: [PATCH v4 2/2] docs: tracing: Refactor index.rst for clarity

[Bagas Sanjaya]

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

On Fri, Mar 21, 2025 at 10:25:07AM -0400, Steven Rostedt wrote:
> Jon,
> 
> Feel free to apply these to your tree.

Hi Jon,

It seems like this series didn't make it to 6.15 merge window. What about
applying it on current cycle (for 6.16) instead? Or should I carry and resubmit
it?

Thanks.

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

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

Re: [PATCH v4 1/2] docs: tracing: Reduce maxdepth in index.rst for clarity

[Bagas Sanjaya]

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

On Tue, Mar 18, 2025 at 05:02:29PM +0530, Purva Yeshi wrote:
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 2c991dc96..fecc4adf7 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

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

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

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