Skip to contentSkip to conversation

docs: some automarkup improvements

PATCH In review Jonathan Corbet 4 participants 11 messages Jun 4, 2025 – Jun 6, 2025

Subsystems (2)
lore
Share & tools
lore

Jonathan Corbet

author maintainer
#0 lore raw

v2 cover docs: some automarkup improvements

A small set of automarkup changes to improve the visual consistency of the rendered HTML documents.

Jonathan Corbet (3):
docs: automarkup: Remove some Sphinx 2 holdovers
docs: automarkup: Mark up undocumented entities too
docs: CSS: make cross-reference links more evident

 Documentation/sphinx-static/custom.css |  7 +++++++
 Documentation/sphinx/automarkup.py     | 27 +++++++++-----------------
 2 files changed, 16 insertions(+), 18 deletions(-)
Signature · 1 line
2.49.0
author maintainer
#1 lore raw

PATCH v2 1/3 docs: automarkup: Remove some Sphinx 2 holdovers

Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind.

---
v2: Remove RE_generic_type as suggested by Mauro

 Documentation/sphinx/automarkup.py | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)
Documentation/sphinx/automarkup.py +2 -16
index fd633f7a0bc3..7828aeac92e7 100644
@@ -22,12 +22,6 @@ from kernel_abi import get_kernel_abi
 #
 RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
 
-#
-# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
-#
-RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
-                             flags=re.ASCII)
-
 #
 # Sphinx 3 uses a different C role for each one of struct, union, enum and
 # typedef
@@ -150,20 +144,12 @@ def markup_func_ref_sphinx3(docname, app, match):
     return target_text
 
 def markup_c_ref(docname, app, match):
-    class_str = {# Sphinx 2 only
-                 RE_function: 'c-func',
-                 RE_generic_type: 'c-type',
-                 # Sphinx 3+ only
-                 RE_struct: 'c-struct',
+    class_str = {RE_struct: 'c-struct',
                  RE_union: 'c-union',
                  RE_enum: 'c-enum',
                  RE_typedef: 'c-type',
                  }
-    reftype_str = {# Sphinx 2 only
-                   RE_function: 'function',
-                   RE_generic_type: 'type',
-                   # Sphinx 3+ only
-                   RE_struct: 'struct',
+    reftype_str = {RE_struct: 'struct',
                    RE_union: 'union',
                    RE_enum: 'enum',
                    RE_typedef: 'type',
Signature · 1 line
2.49.0
Reviewed-by on v2 1/3
#2 lore raw

Re: [PATCH v2 1/3] docs: automarkup: Remove some Sphinx 2 holdovers

Em Wed, 4 Jun 2025 08:36:43 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 4 lines

Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind.

Quoted 46 lines

---
v2: Remove RE_generic_type as suggested by Mauro

 Documentation/sphinx/automarkup.py | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)
Documentation/sphinx/automarkup.py +2 -16
index fd633f7a0bc3..7828aeac92e7 100644
@@ -22,12 +22,6 @@ from kernel_abi import get_kernel_abi
 #
 RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
 
-#
-# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
-#
-RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
-                             flags=re.ASCII)
-
 #
 # Sphinx 3 uses a different C role for each one of struct, union, enum and
 # typedef
@@ -150,20 +144,12 @@ def markup_func_ref_sphinx3(docname, app, match):
     return target_text
 
 def markup_c_ref(docname, app, match):
-    class_str = {# Sphinx 2 only
-                 RE_function: 'c-func',
-                 RE_generic_type: 'c-type',
-                 # Sphinx 3+ only
-                 RE_struct: 'c-struct',
+    class_str = {RE_struct: 'c-struct',
                  RE_union: 'c-union',
                  RE_enum: 'c-enum',
                  RE_typedef: 'c-type',
                  }
-    reftype_str = {# Sphinx 2 only
-                   RE_function: 'function',
-                   RE_generic_type: 'type',
-                   # Sphinx 3+ only
-                   RE_struct: 'struct',
+    reftype_str = {RE_struct: 'struct',
                    RE_union: 'union',
                    RE_enum: 'enum',
                    RE_typedef: 'type',
author maintainer
#3 lore raw

PATCH v2 2/3 docs: automarkup: Mark up undocumented entities too

In reply to Jonathan Corbet

The automarkup code generates markup and a cross-reference link for functions, structs, etc. for which it finds kerneldoc documentation. Undocumented entities are left untouched; that creates an inconsistent reading experience and has caused some writers to go to extra measures to cause the markup to happen.

Mark up detected C entities regardless of whether they are documented.

---
v2: Split out the CSS changes into a separate patch

 Documentation/sphinx/automarkup.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
Documentation/sphinx/automarkup.py +7 -2
index 7828aeac92e7..e67eb8e19c22 100644
@@ -235,8 +235,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
 
     if xref:
         return xref
-
-    return None
+    #
+    # We didn't find the xref; if a container node was supplied,
+    # mark it as a broken xref
+    #
+    if contnode:
+        contnode.set_class("broken_xref")
+    return contnode
 
 #
 # Variant of markup_abi_ref() that warns whan a reference is not found
Signature · 1 line
2.49.0
Reviewed-by on v2 2/3
#4 lore raw

Re: [PATCH v2 2/3] docs: automarkup: Mark up undocumented entities too

Em Wed, 4 Jun 2025 08:36:44 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 9 lines

The automarkup code generates markup and a cross-reference link for functions, structs, etc. for which it finds kerneldoc documentation. Undocumented entities are left untouched; that creates an inconsistent reading experience and has caused some writers to go to extra measures to cause the markup to happen.

Mark up detected C entities regardless of whether they are documented.

Quoted 26 lines

---
v2: Split out the CSS changes into a separate patch

 Documentation/sphinx/automarkup.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
Documentation/sphinx/automarkup.py +7 -2
index 7828aeac92e7..e67eb8e19c22 100644
@@ -235,8 +235,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
 
     if xref:
         return xref
-
-    return None
+    #
+    # We didn't find the xref; if a container node was supplied,
+    # mark it as a broken xref
+    #
+    if contnode:
+        contnode.set_class("broken_xref")
+    return contnode
 
 #
 # Variant of markup_abi_ref() that warns whan a reference is not found
author maintainer
#5 lore raw

PATCH v2 3/3 docs: CSS: make cross-reference links more evident

In reply to Jonathan Corbet

The Sphinx Alabaster theme uses border-bottom to mark reference links; the result does not render correctly (the underline is missing) in some browser configurations. Switch to using the standard text-underline property, and use text-underline-offset to place that underline below any underscores in the underlined text.

---
 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/sphinx-static/custom.css +7 -0
index f4285417c71a..c9991566f914 100644
@@ -136,3 +136,10 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Make xrefs more universally visible */
+a.reference, a.reference:hover {
+    border-bottom: none;
+    text-decoration: underline;
+    text-underline-offset: 0.3em;
+}
Signature · 1 line
2.49.0
Reviewed-by on v2 3/3
#6 lore raw

Re: [PATCH v2 3/3] docs: CSS: make cross-reference links more evident

Em Wed, 4 Jun 2025 08:36:45 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 8 lines

The Sphinx Alabaster theme uses border-bottom to mark reference links; the result does not render correctly (the underline is missing) in some browser configurations. Switch to using the standard text-underline property, and use text-underline-offset to place that underline below any underscores in the underlined text.

While I didn't test, it looks good enough for me.

Quoted 19 lines
---
 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/sphinx-static/custom.css +7 -0
index f4285417c71a..c9991566f914 100644
@@ -136,3 +136,10 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Make xrefs more universally visible */
+a.reference, a.reference:hover {
+    border-bottom: none;
+    text-decoration: underline;
+    text-underline-offset: 0.3em;
+}
Reviewed-by Tested-by on the v2 series
#7 lore raw
In reply to Jonathan Corbet
Quoted 7 lines · Jonathan Corbet

A small set of automarkup changes to improve the visual consistency of the rendered HTML documents.

Jonathan Corbet (3):
docs: automarkup: Remove some Sphinx 2 holdovers
docs: automarkup: Mark up undocumented entities too
docs: CSS: make cross-reference links more evident

This is much better. Markup, links and underlines are all looking good now.

The only other thing I noticed is that the links in the sidebar still use the old style, since they rely on a different CSS selector for some reason:

  div.sphinxsidebar a {
    text-decoration: none;
    border-bottom: 1px dotted #999;
  }

That makes it a bit inconsistent style-wise, so I think it'd be sensible to update that selector as well to follow suit.

In any case,

Thanks,
Nícolas

#8 lore raw
Quoted 10 lines · Nícolas F. R. A. Prado

The only other thing I noticed is that the links in the sidebar still use the old style, since they rely on a different CSS selector for some reason:

  div.sphinxsidebar a {
    text-decoration: none;
    border-bottom: 1px dotted #999;
  }

That makes it a bit inconsistent style-wise, so I think it'd be sensible to update that selector as well to follow suit.

It can be done simply by also applying the same style to aforementioned selector:

---- >8 ----

Documentation/sphinx-static/custom.css +3 -2
index c9991566f91488..14e1bb9c4e63eb 100644
@@ -137,8 +137,9 @@ div.language-selection ul li:hover {
     background: #dddddd;
 }
 
-/* Make xrefs more universally visible */
-a.reference, a.reference:hover {
+/* Make xrefs and sidebar links more universally visible */
+a.reference, a.reference:hover,
+div.sphinxsidebar a {
     border-bottom: none;
     text-decoration: underline;
     text-underline-offset: 0.3em;

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
author maintainer
#9 lore raw
In reply to Nícolas F. R. A. Prado
Quoted 10 lines · Nícolas F. R. A. Prado

The only other thing I noticed is that the links in the sidebar still use the old style, since they rely on a different CSS selector for some reason:

  div.sphinxsidebar a {
    text-decoration: none;
    border-bottom: 1px dotted #999;
  }

That makes it a bit inconsistent style-wise, so I think it'd be sensible to update that selector as well to follow suit.

Sigh. Of course, making it exactly the same doesn't work well due to the shading that we already use in the sidebar. Since we know everything in the sidebar is a link, I suggest something like this:

    a.sphinxsidebar a { border-bottom: none; }
    a.sphinxsidebar a:hover {
    	border-bottom: none;
        text-decoration: underline;
        text-underline-offset: 0.3em;
    }

That makes the sidebar relatively uncluttered, but still lights up the links in a visible way when the pointer passes over them.

Thanks,

jon

#10 lore raw
Quoted 27 lines · Jonathan Corbet
Quoted 5 lines · Nícolas F. R. A. Prado

The only other thing I noticed is that the links in the sidebar still use the
old style, since they rely on a different CSS selector for some reason:

Quoted 8 lines

  div.sphinxsidebar a {
    text-decoration: none;
    border-bottom: 1px dotted #999;
  }

That makes it a bit inconsistent style-wise, so I think it'd be sensible to
update that selector as well to follow suit.

Sigh.  Of course, making it exactly the same doesn't work well due to the shading that we already use in the sidebar.  Since we know everything in the sidebar is a link, I suggest something like this:

    a.sphinxsidebar a { border-bottom: none; }
    a.sphinxsidebar a:hover {
     border-bottom: none;
        text-decoration: underline;
        text-underline-offset: 0.3em;
    }

Quoted 3 lines

That makes the sidebar relatively uncluttered, but still lights up the
links in a visible way when the pointer passes over them.

Personally I'm fine with either approach. Just note that there's a typo there, should be div. not a.:

   div.sphinxsidebar a { border-bottom: none; }
   div.sphinxsidebar a:hover {
       border-bottom: none;
       text-decoration: underline;
       text-underline-offset: 0.3em;
   }
Signature · 2 lines
Thanks,
Nícolas