[PATCH] docs: automarkup: Mark up undocumented entities too

[PATCH] docs: automarkup: Mark up undocumented entities too

[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 <corbet@lwn.net>
---
 Documentation/sphinx-static/custom.css | 5 +++++
 Documentation/sphinx/automarkup.py     | 9 +++++++--
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index f4285417c71a..771984f77307 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -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; }
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 347de81c1ab7..cede07e758a7 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -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
-- 
2.49.0

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Nícolas F. R. A. Prado]

On Tue, Jun 03, 2025 at 11:20:16AM -0600, Jonathan Corbet wrote:
> 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 <corbet@lwn.net>
> ---
>  Documentation/sphinx-static/custom.css | 5 +++++
>  Documentation/sphinx/automarkup.py     | 9 +++++++--
>  2 files changed, 12 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index f4285417c71a..771984f77307 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -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.

> diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> index 347de81c1ab7..cede07e758a7 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -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

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,

Reviewed-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>

Thanks,
Nícolas

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet]

Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:

> 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.

> 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Nícolas F. R. A. Prado]

On Tue, Jun 03, 2025 at 03:12:35PM -0600, Jonathan Corbet wrote:
> Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:
> 
> > 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.

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

> 
> > 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet]

Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:

> On Tue, Jun 03, 2025 at 03:12:35PM -0600, Jonathan Corbet wrote:
>> Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:
>> 
>> > 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.
>
> 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

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.

>> 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Mauro Carvalho Chehab]

Em Tue, 03 Jun 2025 17:04:06 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jonathan Corbet <corbet@lwn.net> writes:
> 
> > 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?

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.

> 
> Thanks,
> 
> jon



Thanks,
Mauro

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Nícolas F. R. A. Prado]

On Wed, Jun 04, 2025 at 09:37:07AM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 03 Jun 2025 17:04:06 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Jonathan Corbet <corbet@lwn.net> writes:
> > 
> > > 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.

> > 
> > 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.

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

> 
> 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet]

Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:

> 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

Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Mauro Carvalho Chehab]

Em Tue, 3 Jun 2025 15:44:42 -0400
Nícolas F. R. A. Prado <nfraprado@collabora.com> escreveu:

> On Tue, Jun 03, 2025 at 11:20:16AM -0600, Jonathan Corbet wrote:
> > 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 <corbet@lwn.net>
> > ---
> >  Documentation/sphinx-static/custom.css | 5 +++++
> >  Documentation/sphinx/automarkup.py     | 9 +++++++--
> >  2 files changed, 12 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> > index f4285417c71a..771984f77307 100644
> > --- a/Documentation/sphinx-static/custom.css
> > +++ b/Documentation/sphinx-static/custom.css
> > @@ -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;
> 	}

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

> 
> 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 ;-)

> 
> > diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> > index 347de81c1ab7..cede07e758a7 100644
> > --- a/Documentation/sphinx/automarkup.py
> > +++ b/Documentation/sphinx/automarkup.py
> > @@ -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  
> 
> 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).

> 
> +    #
> +    # 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,
> 
> Reviewed-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> 
> Thanks,
> Nícolas



Thanks,
Mauro