[PATCH 0/3] Documentation/gpu: reduce verbosity in toc

[PATCH 0/3] Documentation/gpu: reduce verbosity in toc

[Lucas De Marchi]

Checking some issues I was having i915 doc made me look at the toc for
Documentation/gpu. I think it's too hard to read when extending the toc
all levels for each driver. Reduce it to maxdepth=2.

Also fix the usage-stats section appearing in the wrong place.

Lucas De Marchi (3):
  Documentation/gpu: Fix section in the wrong scope
  Documentation/gpu: Limit index to maxdepth=2
  Documentation/gpu: Limit drivers index to maxdepth=2

 Documentation/gpu/drivers.rst         | 1 +
 Documentation/gpu/drm-usage-stats.rst | 1 -
 Documentation/gpu/index.rst           | 1 +
 3 files changed, 2 insertions(+), 1 deletion(-)

-- 
2.38.1

[PATCH 1/3] Documentation/gpu: Fix section in the wrong scope

[Lucas De Marchi]

That section should still be inside "DRM client usage stats" rather than
as a sibling.

Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
---
 Documentation/gpu/drm-usage-stats.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
index 92c5117368d7..b46327356e80 100644
--- a/Documentation/gpu/drm-usage-stats.rst
+++ b/Documentation/gpu/drm-usage-stats.rst
@@ -126,7 +126,6 @@ percentage utilization of the engine, whereas drm-engine-<str> only reflects
 time active without considering what frequency the engine is operating as a
 percentage of it's maximum frequency.
 
-===============================
 Driver specific implementations
 ===============================
 
-- 
2.38.1

[PATCH 2/3] Documentation/gpu: Limit index to maxdepth=2

[Lucas De Marchi]

With a lot of sub-section it's a little bit hard to find the information
needed in the main GPU index. Limit the maxdepth to 2 so it doesn't get
poluted with noise from each driver and from other sections.

Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
---
 Documentation/gpu/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index b99dede9a5b1..1d9402d519be 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -3,6 +3,7 @@ Linux GPU Driver Developer's Guide
 ==================================
 
 .. toctree::
+   :maxdepth: 2
 
    introduction
    drm-internals
-- 
2.38.1

[PATCH 3/3] Documentation/gpu: Limit drivers index to maxdepth=2

[Lucas De Marchi]

Just like the main index, the page generated is very verbose if all the
internal details of each driver is included.

Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
---
 Documentation/gpu/drivers.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 3a52f48215a3..a36ec133b123 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -3,6 +3,7 @@ GPU Driver Documentation
 ========================
 
 .. toctree::
+   :maxdepth: 2
 
    amdgpu/index
    i915
-- 
2.38.1

Re: [PATCH 1/3] Documentation/gpu: Fix section in the wrong scope

[Tvrtko Ursulin]

On 07/11/2022 17:32, Lucas De Marchi wrote:
> That section should still be inside "DRM client usage stats" rather than
> as a sibling.
> 
> Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
> ---
>   Documentation/gpu/drm-usage-stats.rst | 1 -
>   1 file changed, 1 deletion(-)
> 
> diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
> index 92c5117368d7..b46327356e80 100644
> --- a/Documentation/gpu/drm-usage-stats.rst
> +++ b/Documentation/gpu/drm-usage-stats.rst
> @@ -126,7 +126,6 @@ percentage utilization of the engine, whereas drm-engine-<str> only reflects
>   time active without considering what frequency the engine is operating as a
>   percentage of it's maximum frequency.
>   
> -===============================
>   Driver specific implementations
>   ===============================
>   

Oops - yep.

Reviewed-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>

Regards,

Tvrtko

Re: [PATCH 1/3] Documentation/gpu: Fix section in the wrong scope

[Lucas De Marchi]

On Tue, Nov 08, 2022 at 09:49:45AM +0000, Tvrtko Ursulin wrote:
>
>On 07/11/2022 17:32, Lucas De Marchi wrote:
>>That section should still be inside "DRM client usage stats" rather than
>>as a sibling.
>>
>>Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
>>---
>>  Documentation/gpu/drm-usage-stats.rst | 1 -
>>  1 file changed, 1 deletion(-)
>>
>>diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
>>index 92c5117368d7..b46327356e80 100644
>>--- a/Documentation/gpu/drm-usage-stats.rst
>>+++ b/Documentation/gpu/drm-usage-stats.rst
>>@@ -126,7 +126,6 @@ percentage utilization of the engine, whereas drm-engine-<str> only reflects
>>  time active without considering what frequency the engine is operating as a
>>  percentage of it's maximum frequency.
>>-===============================
>>  Driver specific implementations
>>  ===============================
>
>Oops - yep.
>
>Reviewed-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>

thanks, applied this.

Anyone could take a look in the other 2?

thanks
Lucas De Marchi

Re: [Intel-gfx] [PATCH 2/3] Documentation/gpu: Limit index to maxdepth=2

[Balasubramani Vivekanandan]

On 07.11.2022 09:32, Lucas De Marchi wrote:
> With a lot of sub-section it's a little bit hard to find the information
> needed in the main GPU index. Limit the maxdepth to 2 so it doesn't get
> poluted with noise from each driver and from other sections.
> 
> Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
> ---
>  Documentation/gpu/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> index b99dede9a5b1..1d9402d519be 100644
> --- a/Documentation/gpu/index.rst
> +++ b/Documentation/gpu/index.rst
> @@ -3,6 +3,7 @@ Linux GPU Driver Developer's Guide
>  ==================================
>  
>  .. toctree::
> +   :maxdepth: 2

I have a bit different opinion here. I find it helpful to search for a
topic if the headers remain uncollapsed.
A top level view is anyways available in the TOC shown in the left side
of the page which shows only the immediate next level headers.

Regards,
Bala
>  
>     introduction
>     drm-internals
> -- 
> 2.38.1
> 

Re: [Intel-gfx] [PATCH 2/3] Documentation/gpu: Limit index to maxdepth=2

[Lucas De Marchi]

On Tue, Nov 15, 2022 at 03:18:01PM +0530, Balasubramani Vivekanandan wrote:
>On 07.11.2022 09:32, Lucas De Marchi wrote:
>> With a lot of sub-section it's a little bit hard to find the information
>> needed in the main GPU index. Limit the maxdepth to 2 so it doesn't get
>> poluted with noise from each driver and from other sections.
>>
>> Signed-off-by: Lucas De Marchi <lucas.demarchi@intel.com>
>> ---
>>  Documentation/gpu/index.rst | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
>> index b99dede9a5b1..1d9402d519be 100644
>> --- a/Documentation/gpu/index.rst
>> +++ b/Documentation/gpu/index.rst
>> @@ -3,6 +3,7 @@ Linux GPU Driver Developer's Guide
>>  ==================================
>>
>>  .. toctree::
>> +   :maxdepth: 2
>
>I have a bit different opinion here. I find it helpful to search for a
>topic if the headers remain uncollapsed.
>A top level view is anyways available in the TOC shown in the left side
>of the page which shows only the immediate next level headers.

I think the left side doesn't render very well. I'd still like to have
depth 2 for an overview, without going too deep in the innerworks of
each and every driver. Looking around I found there is a lot of use of
maxdepth in the indexes (git grep ":maxdepth:" -- Documentation), so
thought it would be something to adopt here.  Anyway, I don't mind
dropping these 2 patches if people don't agree with me :)


thanks
Lucas De Marchi