[PATCH] drm/i915: Maintain consistent documentation subsection ordering

[Jani Nikula]

On Thu, 23 May 2019, Jonathan Corbet <corbet at lwn.net> wrote:
> With Sphinx 2.0 (or prior versions with the deprecation warnings fixed) the
> docs build fails with:
>
>   Documentation/gpu/i915.rst:403: WARNING: Title level inconsistent:
>
>   Global GTT Fence Handling
>   ~~~~~~~~~~~~~~~~~~~~~~~~~
>
>   reST markup error:
>   Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent:
>
> I "fixed" it by changing the subsections in i915.rst, but that didn't seem
> like the correct change.  It turns out that a couple of i915 files create
> their own subsections in kerneldoc comments using apostrophes as the
> heading marker:
>
>   Layout
>   ''''''
>
> That breaks the normal subsection marker ordering, and newer Sphinx is
> rather more strict about enforcing that ordering.  So fix the offending
> comments to make Sphinx happy.
>
> (This is unfortunate, in that kerneldoc comments shouldn't need to be aware
> of where they might be included in the heading hierarchy, but I don't see
> a better way around it).
>
> Signed-off-by: Jonathan Corbet <corbet at lwn.net>
> ---
> [If I can possibly get an ack for this, I would like to send it up soon
> with the other Sphinx-related fixes.]

Thanks, whatever works,

Acked-by: Jani Nikula <jani.nikula at intel.com>


>
>  drivers/gpu/drm/i915/i915_reg.h          | 6 +++---
>  drivers/gpu/drm/i915/intel_workarounds.c | 2 +-
>  2 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/i915_reg.h b/drivers/gpu/drm/i915/i915_reg.h
> index b74824f0b5b1..249d35c12a75 100644
> --- a/drivers/gpu/drm/i915/i915_reg.h
> +++ b/drivers/gpu/drm/i915/i915_reg.h
> @@ -35,7 +35,7 @@
>   * macros. Do **not** mass change existing definitions just to update the style.
>   *
>   * Layout
> - * ''''''
> + * ~~~~~~
>   *
>   * Keep helper macros near the top. For example, _PIPE() and friends.
>   *
> @@ -79,7 +79,7 @@
>   * style. Use lower case in hexadecimal values.
>   *
>   * Naming
> - * ''''''
> + * ~~~~~~
>   *
>   * Try to name registers according to the specs. If the register name changes in
>   * the specs from platform to another, stick to the original name.
> @@ -97,7 +97,7 @@
>   * suffix to the name. For example, ``_SKL`` or ``_GEN8``.
>   *
>   * Examples
> - * ''''''''
> + * ~~~~~~~~
>   *
>   * (Note that the values in the example are indented using spaces instead of
>   * TABs to avoid misalignment in generated documentation. Use TABs in the
> diff --git a/drivers/gpu/drm/i915/intel_workarounds.c b/drivers/gpu/drm/i915/intel_workarounds.c
> index 9682dd575152..6decd432f4d3 100644
> --- a/drivers/gpu/drm/i915/intel_workarounds.c
> +++ b/drivers/gpu/drm/i915/intel_workarounds.c
> @@ -37,7 +37,7 @@
>   *    costly and simplifies things. We can revisit this in the future.
>   *
>   * Layout
> - * ''''''
> + * ~~~~~~
>   *
>   * Keep things in this file ordered by WA type, as per the above (context, GT,
>   * display, register whitelist, batchbuffer). Then, inside each type, keep the

-- 
Jani Nikula, Intel Open Source Graphics Center