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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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