docs: automarkup: Mark up undocumented entities too
Subsystems (2)
Jonathan Corbet
maintainerPATCH 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
@@ -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
@@ -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
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.
Signed-off-by Jonathan Corbet <[email protected]>--- 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
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@@ -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
-2return 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
Jonathan Corbet
maintainerQuoted 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
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
Jonathan Corbet
maintainerQuoted 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
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
Jonathan Corbet
maintainerQuoted 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
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
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
Jonathan Corbet
maintainerQuoted 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
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.
Signed-off-by Jonathan Corbet <[email protected]>--- Documentation/sphinx-static/custom.css | 5 +++++ Documentation/sphinx/automarkup.py | 9 +++++++-- 2 files changed, 12 insertions(+), 2 deletions(-)Documentation/sphinx-static/custom.css +0
-0Documentation/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@@ -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
-2if 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 contnodeAnd 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,
Reviewed-by Nícolas F. R. A. Prado <[email protected]>Thanks,
Nícolas
Thanks,
Mauro