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

["Nícolas F. R. A. Prado" <nfraprado@collabora.com>]

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