diff mbox series

drm/i915: Maintain consistent documentation subsection ordering

Message ID 20190523101631.64fb33c0@lwn.net (mailing list archive)
State New, archived
Headers show
Series drm/i915: Maintain consistent documentation subsection ordering | expand

Commit Message

Jonathan Corbet May 23, 2019, 4:16 p.m. UTC
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@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.]

 drivers/gpu/drm/i915/i915_reg.h          | 6 +++---
 drivers/gpu/drm/i915/intel_workarounds.c | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

Comments

Jani Nikula May 24, 2019, 7:24 a.m. UTC | #1
On Thu, 23 May 2019, Jonathan Corbet <corbet@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@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@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
diff mbox series

Patch

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