Re: [PATCH] drm/xe: xe_guc_pc.c: fix DOC underlines

[Rodrigo Vivi <rodrigo.vivi@intel.com>]

On Mon, Oct 13, 2025 at 11:28:26AM -0700, Randy Dunlap wrote:
> Apparently a recent change in docutils has made checking of section
> heading levels (underline style) be more careful.
> 
> There are 2 heading underline style errors reported here. Repair them by
> changing the underline style from Chapter (using '=') to Section (using
> '-') since they are used within a Chapter already (in xe_firmware.rst).
> 
> """
> Documentation/gpu/xe/xe_firmware.rst:31: drivers/gpu/drm/xe/xe_guc_pc.c:75: ERROR: A level 2 section cannot be used here.
> 
> Frequency management:
> =====================
> 
> Established title styles: =/= =
> 
> The parent of level 2 sections cannot be reached. The parser is at section level 2 but the current node has only 0 parent section(s).
> One reason may be a high level section used in a directive that parses its content into a base node not attached to the document
> (up to Docutils 0.21, these sections were silently dropped). [docutils]
> Documentation/gpu/xe/xe_firmware:31: ../drivers/gpu/drm/xe/xe_guc_pc.c:86: ERROR: A level 2 section cannot be used here.
> 
> Render-C States:
> ================
> 
> Established title styles: =/= =
> 
> The parent of level 2 sections cannot be reached. The parser is at section level 2 but the current node has only 0 parent section(s).
> One reason may be a high level section used in a directive that parses its content into a base node not attached to the document
> (up to Docutils 0.21, these sections were silently dropped). [docutils]

Nothing against this change, but I'd like to understand more on what has
actually changed. I have docutils 0.21.2 here and I cannot see this error.

Perhaps it was a temporary bug in docutils 0.21.0 or 0.21.1 ?

rdvivi@rdvivi-mobl1:~/linux/drm-tip$ touch drivers/gpu/drm/xe/xe_guc_pc.c
rdvivi@rdvivi-mobl1:~/linux/drm-tip$ touch Documentation/gpu/xe/xe_firmware.rst 

rdvivi@rdvivi-mobl1:~/linux/drm-tip$ git status
On branch drm-tip
Your branch is up to date with 'tip/drm-tip'.

You are in the middle of an am session.
  (fix conflicts and then run "git am --continue")
  (use "git am --skip" to skip this patch)
  (use "git am --abort" to restore the original branch)

nothing to commit, working tree clean

rdvivi@rdvivi-mobl1:~/linux/drm-tip$ make htmldocs
Python version: 3.13.8
Docutils version: 0.21.2
Using alabaster theme
Using Python kernel-doc
rdvivi@rdvivi-mobl1:~/linux/drm-tip$ rm -rf Documentation/output/gpu
rdvivi@rdvivi-mobl1:~/linux/drm-tip$ make htmldocs

then I only see those ugly but expected hwmon warnings, and none of the
issues described here.

> """
> 
> Fixes: dd08ebf6c352 ("drm/xe: Introduce a new DRM driver for Intel GPUs")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Sorry for the resend. I didn't have .gitconfig present so parts of
> this didn't work as intended.
> 
> Cc: Matthew Brost <matthew.brost@intel.com>
> Cc: Lucas De Marchi <lucas.demarchi@intel.com>
> Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
> Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
> Cc: intel-xe@lists.freedesktop.org
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Maxime Ripard <mripard@kernel.org>
> Cc: Thomas Zimmermann <tzimmermann@suse.de>
> Cc: David Airlie <airlied@gmail.com>
> Cc: Simona Vetter <simona@ffwll.ch>
> ---
>  drivers/gpu/drm/xe/xe_guc_pc.c |    8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> --- linux-next-20251010.orig/drivers/gpu/drm/xe/xe_guc_pc.c
> +++ linux-next-20251010/drivers/gpu/drm/xe/xe_guc_pc.c
> @@ -74,8 +74,8 @@
>   * connected power conservation features in the GuC firmware. The firmware
>   * exposes a programming interface to the host for the control of SLPC.
>   *
> - * Frequency management:
> - * =====================
> + * Frequency management
> + * --------------------
>   *
>   * Xe driver enables SLPC with all of its defaults features and frequency
>   * selection, which varies per platform.
> @@ -85,8 +85,8 @@
>   * thus saving power. Base profile is default and ensures balanced performance
>   * for any workload.
>   *
> - * Render-C States:
> - * ================
> + * Render-C States
> + * ---------------
>   *
>   * Render-C states is also a GuC PC feature that is now enabled in Xe for
>   * all platforms.