Skip to contentSkip to conversation

docs: automarkup: Mark up undocumented entities too

PATCH In review Jonathan Corbet 3 participants 10 messages Jun 3, 2025 – Jun 4, 2025

Subsystems (2)
lore
Share & tools
lore

Jonathan Corbet

author maintainer
#0 lore raw

PATCH 1/1 docs: automarkup: Mark up undocumented entities too

The automarkup code generates markup and a cross-reference links 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. Change the CSS, though, to underline the entities that actually link to documentation, making our docs a bit more consistent with longstanding WWW practice and allowing readers to tell the difference.

---
 Documentation/sphinx-static/custom.css | 5 +++++
 Documentation/sphinx/automarkup.py     | 9 +++++++--
 2 files changed, 12 insertions(+), 2 deletions(-)
Documentation/sphinx-static/custom.css +5 -0
index f4285417c71a..771984f77307 100644
@@ -136,3 +136,8 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Mark xrefs with an underline, but elide it for those that
+   don't lead anywhere */
+.xref { text-decoration: underline; }
+.broken_xref { text-decoration: none !important; }
Documentation/sphinx/automarkup.py +7 -2
index 347de81c1ab7..cede07e758a7 100644
@@ -241,8 +241,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 v1 1/1
#1 lore raw
Quoted 22 lines · Jonathan Corbet

The automarkup code generates markup and a cross-reference links 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. Change the CSS, though, to underline the entities that actually link to documentation, making our docs a bit more consistent with longstanding WWW practice and allowing readers to tell the difference.

---
 Documentation/sphinx-static/custom.css | 5 +++++
 Documentation/sphinx/automarkup.py     | 9 +++++++--
 2 files changed, 12 insertions(+), 2 deletions(-)
Documentation/sphinx-static/custom.css +0 -0
index f4285417c71a..771984f77307 100644

Documentation/sphinx-static/custom.css div.language-selection:hover ul { · line 143

Quoted 8 lines
Documentation/sphinx-static/custom.css +5 -0
@@ -136,3 +136,8 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Mark xrefs with an underline, but elide it for those that
+   don't lead anywhere */
+.xref { text-decoration: underline; }
+.broken_xref { text-decoration: none !important; }

To me the results look much better without these CSS rules, as they cause a double underline.

The current CSS already adds a dotted underline to reference links through the following rule:

	a.reference {
	  border-bottom: 1px dotted #004B6B;
	}

So when you add this underline text-decoration to the .xref tags, the ones inside <a> tags (valid xrefs) end up with two underlines.

I've checked the result for both struct and functions and they work the same.

So I suggest just dropping these CSS rules.

Quoted 7 lines
Documentation/sphinx/automarkup.py +0 -0
index 347de81c1ab7..cede07e758a7 100644
@@ -241,8 +241,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
 
     if xref:

Documentation/sphinx/automarkup.py def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): · line 250

Quoted 10 lines
Documentation/sphinx/automarkup.py +7 -2
         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

And accordingly changing this to just:

+    #
+    # We didn't find the xref; return contnode so that if one was supplied the
+    # resulting node can have the same styling (eg literal formatting for
+    # struct/functions)
+    #
+    return contnode

With that,

Thanks,
Nícolas

author maintainer
#2 lore raw
Quoted 9 lines · Nícolas F. R. A. Prado

To me the results look much better without these CSS rules, as they cause a double underline.

The current CSS already adds a dotted underline to reference links through the following rule:

	a.reference {
	  border-bottom: 1px dotted #004B6B;
	}

OK, that is interesting ... I don't see that underline.

Are you using the (default) alabaster theme? Alabaster explicitly sets it to "none", as can be seen on docs.kernel.org.

Quoted 6 lines

So when you add this underline text-decoration to the .xref tags, the ones inside <a> tags (valid xrefs) end up with two underlines.

I've checked the result for both struct and functions and they work the same.

So I suggest just dropping these CSS rules.

We need to figure out why you are seeing something different. But I do want rules to distinguish just-plain-function from function-with-kerneldoc.

Thanks,

jon

#3 lore raw
Quoted 8 lines · Jonathan Corbet
Quoted 6 lines · Nícolas F. R. A. Prado

To me the results look much better without these CSS rules, as they cause a double underline.

The current CSS already adds a dotted underline to reference links through the following rule:

Quoted 8 lines
Quoted 3 lines
	a.reference {
	  border-bottom: 1px dotted #004B6B;
	}

OK, that is interesting ... I don't see that underline.

Are you using the (default) alabaster theme? Alabaster explicitly sets it to "none", as can be seen on docs.kernel.org.

Yes. And I also see this same dotted underline on docs.kernel.org, for every URL on that page. I've also double-checked this is the case when accessing from my phone, and in incognito, so maybe this is something on your end?

To be clear, you don't see underlines on any URLs on docs.kernel.org?

You could find the CSS rule I mentioned above in

https://docs.kernel.org/_static/alabaster.css

Quoted 11 lines
Quoted 7 lines

So when you add this underline text-decoration to the .xref tags, the ones inside <a> tags (valid xrefs) end up with two underlines.

I've checked the result for both struct and functions and they work the same.

So I suggest just dropping these CSS rules.

We need to figure out why you are seeing something different. But I do want rules to distinguish just-plain-function from function-with-kerneldoc.

Maybe I wasn't clear, but on my end they are already rendered differently with your change in automarkup.py, but without the CSS change. Both show up as bold monospaced texts, but only in the case where the link is valid is there a <a> tag, so only that one gets this dotted underline. When the xref doesn't exist there's no underline.

Thanks,
Nícolas

author maintainer
#4 lore raw
Quoted 22 lines · Nícolas F. R. A. Prado
Quoted 8 lines · Jonathan Corbet
Quoted 6 lines · Nícolas F. R. A. Prado

To me the results look much better without these CSS rules, as they cause a double underline.

The current CSS already adds a dotted underline to reference links through the following rule:

Quoted 8 lines
Quoted 3 lines
	a.reference {
	  border-bottom: 1px dotted #004B6B;
	}

OK, that is interesting ... I don't see that underline.

Are you using the (default) alabaster theme? Alabaster explicitly sets it to "none", as can be seen on docs.kernel.org.

Yes. And I also see this same dotted underline on docs.kernel.org, for every URL on that page. I've also double-checked this is the case when accessing from my phone, and in incognito, so maybe this is something on your end?

Quoted 5 lines

To be clear, you don't see underlines on any URLs on docs.kernel.org?

You could find the CSS rule I mentioned above in

https://docs.kernel.org/_static/alabaster.css

OK, this is downright mysterious. It's using borders, which is weird... for me, that "border" does not render, even though the browser claims it has a 1px width, as expected. I get this behavior both in Firefox and with a bog-standard, thoroughly unconfigured Chromium I keep around for just this kind of purpose.

Chrome on the phone shows a faint underline, firefox does not.

Quoted 9 lines
Quoted 3 lines

We need to figure out why you are seeing something different. But I do want rules to distinguish just-plain-function from function-with-kerneldoc.

Maybe I wasn't clear, but on my end they are already rendered differently with your change in automarkup.py, but without the CSS change. Both show up as bold monospaced texts, but only in the case where the link is valid is there a <a> tag, so only that one gets this dotted underline. When the xref doesn't exist there's no underline.

OK, I can see that would happen that way - at least, if it actually worked as expected.

I wonder why they used a border rather than the text-decoration that is there for exactly that purpose? I'm inclined to change the CSS to get reliable underlining for everybody.

Thanks,

jon

author maintainer
#5 lore raw
Quoted 3 lines · Jonathan Corbet

I wonder why they used a border rather than the text-decoration that is there for exactly that purpose? I'm inclined to change the CSS to get reliable underlining for everybody.

Having played with this a bit, I'm guessing they went with the border because the text-decoration underline gets mixed up with underscores in function names, while the border sits below the underscore.

Assuming we want to preserve that behavior, tossing in a line like:

border-bottom-width: 2px;

makes those underlines (that I never even knew existed :) visible. So maybe that's the approach to take?

Thanks,

jon

#6 lore raw

Em Tue, 03 Jun 2025 17:04:06 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 10 lines
Quoted 3 lines · Jonathan Corbet

I wonder why they used a border rather than the text-decoration that is there for exactly that purpose? I'm inclined to change the CSS to get reliable underlining for everybody.

Having played with this a bit, I'm guessing they went with the border because the text-decoration underline gets mixed up with underscores in function names, while the border sits below the underscore.

Quoted 6 lines

Assuming we want to preserve that behavior, tossing in a line like:

border-bottom-width: 2px;

makes those underlines (that I never even knew existed :) visible. So maybe that's the approach to take?

What I suspect is that this could be related to your monitor's DPI, and eventually to WM scaling. When you used a larger size, it became visible.

I would override CSS and replace a.reference to disable border and enable text decoration, as this is probably more portable.

Still, I think it is worth to have separate CSS classes for xref and broken xref, as if one wants to do a different decoration, that would be possible.

Quoted 4 lines

Thanks,

jon

Thanks,
Mauro

#7 lore raw
Quoted 12 lines · Mauro Carvalho Chehab

Em Tue, 03 Jun 2025 17:04:06 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 9 lines
Quoted 3 lines · Jonathan Corbet

I wonder why they used a border rather than the text-decoration that is there for exactly that purpose? I'm inclined to change the CSS to get reliable underlining for everybody.

Having played with this a bit, I'm guessing they went with the border because the text-decoration underline gets mixed up with underscores in function names, while the border sits below the underscore.

FWIW, I haven't tested it, but it looks like there's a text-underline-offset CSS property that could be used if you do want to use text-decoration for better semantics/portability but prevent it from clashing with the underlines which would impact legibility.

Quoted 8 lines
Quoted 7 lines

Assuming we want to preserve that behavior, tossing in a line like:

border-bottom-width: 2px;

makes those underlines (that I never even knew existed :) visible. So maybe that's the approach to take?

Quoted 6 lines

What I suspect is that this could be related to your monitor's DPI, and eventually to WM scaling. When you used a larger size, it became visible.

I would override CSS and replace a.reference to disable border and enable text decoration, as this is probably more portable.

Assuming the offset property I mentioned above works this sounds sensible to me. I just wouldn't want legibility to be degraded.

Quoted 4 lines

Still, I think it is worth to have separate CSS classes for xref and broken xref, as if one wants to do a different decoration, that would be possible.

Yeah, makes sense, no drawback in having it really.

Thanks,
Nícolas

author maintainer
#8 lore raw
Quoted 4 lines · Nícolas F. R. A. Prado

FWIW, I haven't tested it, but it looks like there's a text-underline-offset CSS property that could be used if you do want to use text-decoration for better semantics/portability but prevent it from clashing with the underlines which would impact legibility.

Ah ... I hadn't known about that. Of course there's an obscure CSS knob ... it works pretty well. I'll send a new version using that shortly, thanks for the suggestion!

jon

#9 lore raw
In reply to Nícolas F. R. A. Prado

Em Tue, 3 Jun 2025 15:44:42 -0400
Nícolas F. R. A. Prado <[email protected]> escreveu:

Quoted 35 lines · Jonathan Corbet
Quoted 22 lines

The automarkup code generates markup and a cross-reference links 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. Change the CSS, though, to underline the entities that actually link to documentation, making our docs a bit more consistent with longstanding WWW practice and allowing readers to tell the difference.

---
 Documentation/sphinx-static/custom.css | 5 +++++
 Documentation/sphinx/automarkup.py     | 9 +++++++--
 2 files changed, 12 insertions(+), 2 deletions(-)
Documentation/sphinx-static/custom.css +0 -0
index f4285417c71a..771984f77307 100644

Documentation/sphinx-static/custom.css div.language-selection:hover ul { · line 143

Quoted 8 lines
Documentation/sphinx-static/custom.css +5 -0
@@ -136,3 +136,8 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Mark xrefs with an underline, but elide it for those that
+   don't lead anywhere */
+.xref { text-decoration: underline; }
+.broken_xref { text-decoration: none !important; }  

To me the results look much better without these CSS rules, as they cause a double underline.

Quoted 6 lines

The current CSS already adds a dotted underline to reference links through the following rule:

	a.reference {
	  border-bottom: 1px dotted #004B6B;
	}

I like the idea of having different CSS classes for xref and broken_xref, as it allows better formatting. I didn't test, but IMO we can either change a.reference to use text-decoration: underline or to override border-bottom for .xref (does it need also for .broken_xref?), e.g.:

	.xref {
		text-decoration: underline; 
		border-bottom: none;
	}

By placing both text-decoration and border-bottom, we can ensure that whatever default on whatever CSS used, this will display just one underline(*).

(*) such default can still be overridden with:

make DOCS_CSS=custom.css

Quoted 7 lines

So when you add this underline text-decoration to the .xref tags, the ones inside <a> tags (valid xrefs) end up with two underlines.

I've checked the result for both struct and functions and they work the same.

So I suggest just dropping these CSS rules.

I suggest keep them ;-)

Quoted 7 lines
Quoted 7 lines
Documentation/sphinx/automarkup.py +0 -0
index 347de81c1ab7..cede07e758a7 100644
@@ -241,8 +241,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
 
Quoted 13 lines

Documentation/sphinx/automarkup.py def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): · line 250

Quoted 11 lines
Documentation/sphinx/automarkup.py +7 -2
     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  

And accordingly changing this to just:

Better to keep it. Having a different class here helps if someone wants to have a custom CSS that, for instance, would bold the undocumented functions (for instance using a red background).

Quoted 8 lines
Documentation/sphinx/automarkup.py +6 -0
+    #
+    # We didn't find the xref; return contnode so that if one was supplied the
+    # resulting node can have the same styling (eg literal formatting for
+    # struct/functions)
+    #
+    return contnode
Quoted 6 lines

With that,

Thanks,
Nícolas

Thanks,
Mauro