linux-kernel - [PATCH 5.1 66/70] drm/i915: Maintain consistent documentation subsection ordering

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20190609164132.953760538@linuxfoundation.org>
Date:   Sun,  9 Jun 2019 18:42:17 +0200
From:   Greg Kroah-Hartman <gregkh@...uxfoundation.org>
To:     linux-kernel@...r.kernel.org
Cc:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        stable@...r.kernel.org, Jani Nikula <jani.nikula@...el.com>,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH 5.1 66/70] drm/i915: Maintain consistent documentation subsection ordering

From: Jonathan Corbet <corbet@....net>

commit 551bd3368a7b3cfef01edaade8970948d178d40a upstream.

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).

Cc: stable@...r.kernel.org  # v4.14+
Acked-by: Jani Nikula <jani.nikula@...el.com>
Signed-off-by: Jonathan Corbet <corbet@....net>
Signed-off-by: Greg Kroah-Hartman <gregkh@...uxfoundation.org>

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

--- a/drivers/gpu/drm/i915/i915_reg.h
+++ b/drivers/gpu/drm/i915/i915_reg.h
@@ -32,7 +32,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.
  *
@@ -78,7 +78,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.
@@ -96,7 +96,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
--- 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