linux-next: build warning after merge of the powerpc tree

Hi all,

After merging the powerpc tree, today's linux-next build (htmldocs)
produced this warning:

docutils.utils.SystemMessage: Documentation/powerpc/associativity.rst:1: (SEVERE/4) Title overline & underline mismatch.

============================
NUMA resource associativity
=============================

Introduced by commit

  1c6b5a7e7405 ("powerpc/pseries: Add support for FORM2 associativity")

There are other obvious problems with this document (but sphinx seems
to have hung before it reported them).

Like

Form 0
-----

and

Form 1
-----

and

Form 2
-------

-- 
Cheers,
Stephen Rothwell

Hi all,

[cc'ing Jon in case he can fix the sphix hang - or knows anything about it]

On Mon, 23 Aug 2021 19:55:40 +1000 Stephen Rothwell [off-list ref] wrote:

After merging the powerpc tree, today's linux-next build (htmldocs)
produced this warning:

I missed a line:

Sphinx parallel build error:

docutils.utils.SystemMessage: Documentation/powerpc/associativity.rst:1: (SEVERE/4) Title overline & underline mismatch.

============================
NUMA resource associativity
=============================

Introduced by commit

  1c6b5a7e7405 ("powerpc/pseries: Add support for FORM2 associativity")

There are other obvious problems with this document (but sphinx seems
to have hung before it reported them).

Like

Form 0
-----

and

Form 1
-----

and

Form 2
-------

I also get the following warning:

Documentation/powerpc/associativity.rst: WARNING: document isn't included in any toctree

And applying the following patch is enough to allow sphinx to finish
(rather than livelocking):

diff --git a/Documentation/powerpc/associativity.rst b/Documentation/powerpc/associativity.rst
index 07e7dd3d6c87..b77c6ccbd6cb 100644
--- a/Documentation/powerpc/associativity.rst
+++ b/Documentation/powerpc/associativity.rst

@@ -1,6 +1,6 @@
-============================
+===========================
 NUMA resource associativity
-=============================
+===========================
 
 Associativity represents the groupings of the various platform resources into
 domains of substantially similar mean performance relative to resources outside

@@ -20,11 +20,11 @@ A value of 1 indicates the usage of Form 1 associativity. For Form 2 associativi
 bit 2 of byte 5 in the "ibm,architecture-vec-5" property is used.
 
 Form 0
------
+------
 Form 0 associativity supports only two NUMA distances (LOCAL and REMOTE).
 
 Form 1
------
+------
 With Form 1 a combination of ibm,associativity-reference-points, and ibm,associativity
 device tree properties are used to determine the NUMA distance between resource groups/domains.
 

@@ -45,7 +45,7 @@ level of the resource group, the kernel doubles the NUMA distance between the
 comparing domains.
 
 Form 2
--------
+------
 Form 2 associativity format adds separate device tree properties representing NUMA node distance
 thereby making the node distance computation flexible. Form 2 also allows flexible primary
 domain numbering. With numa distance computation now detached from the index value in

-- 
Cheers,
Stephen Rothwell

Stephen Rothwell [off-list ref] writes:

Hi all,

[cc'ing Jon in case he can fix the sphix hang - or knows anything about it]

That's new to me.  Which version of sphinx?

jon

Hi Jona,

On Mon, 23 Aug 2021 08:19:30 -0600 Jonathan Corbet [off-list ref] wrote:

Stephen Rothwell [off-list ref] writes:

quoted

Hi all,

[cc'ing Jon in case he can fix the sphix hang - or knows anything about it]  

That's new to me.  Which version of sphinx?

3.4.3-2, its a Debian version.

-- 
Cheers,
Stephen Rothwell

Stephen Rothwell [off-list ref] writes:

Thanks for looking into this. I guess we also need to format the below table?

  | 0    8   40
--|------------
  |
0 | 10   20  80
  |
8 | 20   10  160
  |
40| 80   160  10


I don't know how to represent that in the documentation file. A table is
probably not the right one?

-aneesh

"Aneesh Kumar K.V" [off-list ref] writes:

Thanks for looking into this. I guess we also need to format the below table?

  | 0    8   40
--|------------
  |
0 | 10   20  80
  |
8 | 20   10  160
  |
40| 80   160  10


I don't know how to represent that in the documentation file. A table is
probably not the right one?

The cheap way out is to put it in a literal block, of course.  Sphinx
makes tables pretty easy, though:

  https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

jon