Re: PDF misery

[Vegard Nossum <vegard.nossum@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 866 bytes --]


On 18/02/2024 11:08, Vegard Nossum wrote:
> I think the "bug" here is really that Sphinx generated LaTeX code that
> doesn't build -- and that it didn't warn about the problem in other
> modes (maybe it does in newer versions, or maybe we overlooked the
> warnings?).
> 
> If we'd had those warnings then we could have stopped those constructs
> from entering the documentation sources to start with.

With the attached patch I get:

$ make htmldocs SPHINXDIRS=filesystems/xfs
make[3]: Nothing to be done for 'html'.
Using alabaster theme
source directory: filesystems/xfs
WARNING: xfs-online-fsck-design.rst:2096: heading "Case Study: Sorting 
xfarrays" has nesting level 7; consider restructuring

Maybe we can do the same for itemize lists.

I didn't check what impact this potentially has on running time. Also
only tested with Sphinx 4.3.2.

Thoughts?


Vegard

[-- Attachment #2: kvalidate.patch --]
[-- Type: text/x-patch, Size: 1958 bytes --]

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5830b01c5642..1cfcea4e487d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -55,7 +55,8 @@ needs_sphinx = '2.4.4'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat', 'translations']
+              'kernel_abi', 'kernel_feat', 'translations',
+              'kvalidate']
 
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
diff --git a/Documentation/sphinx/kvalidate.py b/Documentation/sphinx/kvalidate.py
new file mode 100644
index 000000000000..3302e936db77
--- /dev/null
+++ b/Documentation/sphinx/kvalidate.py
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# Copyright © 2024, Oracle and/or its affiliates.
+# Author: Vegard Nossum <vegard.nossum@oracle.com>
+#
+# Validate doc tree against kernel-specific rules.
+#
+
+import os
+
+import docutils
+from sphinx.util import logging
+
+logger = logging.getLogger('kerneldoc')
+
+max_heading_levels = 5
+
+def process_doctree(app, doctree):
+    env = app.env
+    srcdir = env.srcdir
+
+    for node in doctree.traverse(docutils.nodes.title):
+        heading_level = 0
+
+        ancestor = node.parent
+        while ancestor is not None:
+            if isinstance(ancestor, docutils.nodes.section):
+                heading_level = heading_level + 1
+
+            ancestor = ancestor.parent
+
+        if heading_level > max_heading_levels:
+            logger.warning("%s:%u: heading \"%s\" has nesting level %u; consider restructuring",
+                os.path.relpath(node.source, srcdir), node.line, node.astext(), heading_level + 1)
+
+def setup(app):
+    app.connect('doctree-read', process_doctree)
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }