A small set of automarkup changes to improve the visual consistency
of the rendered HTML documents.

Jonathan Corbet (3):
  docs: automarkup: Remove some Sphinx 2 holdovers
  docs: automarkup: Mark up undocumented entities too
  docs: CSS: make cross-reference links more evident

 Documentation/sphinx-static/custom.css |  7 +++++++
 Documentation/sphinx/automarkup.py     | 27 +++++++++-----------------
 2 files changed, 16 insertions(+), 18 deletions(-)

-- 
2.49.0

On Wed, Jun 04, 2025 at 08:36:42AM -0600, Jonathan Corbet wrote:
> A small set of automarkup changes to improve the visual consistency
> of the rendered HTML documents.
> 
> Jonathan Corbet (3):
>   docs: automarkup: Remove some Sphinx 2 holdovers
>   docs: automarkup: Mark up undocumented entities too
>   docs: CSS: make cross-reference links more evident

This is much better. Markup, links and underlines are all looking good now.

The only other thing I noticed is that the links in the sidebar still use the
old style, since they rely on a different CSS selector for some reason:

  div.sphinxsidebar a {
    text-decoration: none;
    border-bottom: 1px dotted #999;
  }

That makes it a bit inconsistent style-wise, so I think it'd be sensible to
update that selector as well to follow suit.

In any case,

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

Thanks,
Nícolas

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

> The only other thing I noticed is that the links in the sidebar still use the
> old style, since they rely on a different CSS selector for some reason:
>
>   div.sphinxsidebar a {
>     text-decoration: none;
>     border-bottom: 1px dotted #999;
>   }
>
> That makes it a bit inconsistent style-wise, so I think it'd be sensible to
> update that selector as well to follow suit.

Sigh.  Of course, making it exactly the same doesn't work well due to
the shading that we already use in the sidebar.  Since we know
everything in the sidebar is a link, I suggest something like this:

    a.sphinxsidebar a { border-bottom: none; }
    a.sphinxsidebar a:hover {
    	border-bottom: none;
        text-decoration: underline;
        text-underline-offset: 0.3em;
    }

That makes the sidebar relatively uncluttered, but still lights up the
links in a visible way when the pointer passes over them.

Thanks,

jon

On Thu, 2025-06-05 at 10:32 -0600, Jonathan Corbet wrote:
> Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:
> 
> > The only other thing I noticed is that the links in the sidebar
> > still use the
> > old style, since they rely on a different CSS selector for some
> > reason:
> > 
> >   div.sphinxsidebar a {
> >     text-decoration: none;
> >     border-bottom: 1px dotted #999;
> >   }
> > 
> > That makes it a bit inconsistent style-wise, so I think it'd be
> > sensible to
> > update that selector as well to follow suit.
> 
> Sigh.  Of course, making it exactly the same doesn't work well due to
> the shading that we already use in the sidebar.  Since we know
> everything in the sidebar is a link, I suggest something like this:
> 
>     a.sphinxsidebar a { border-bottom: none; }
>     a.sphinxsidebar a:hover {
>     	border-bottom: none;
>         text-decoration: underline;
>         text-underline-offset: 0.3em;
>     }
> 
> That makes the sidebar relatively uncluttered, but still lights up
> the
> links in a visible way when the pointer passes over them.

Personally I'm fine with either approach. Just note that there's a typo
there, should be div. not a.:

   div.sphinxsidebar a { border-bottom: none; }
   div.sphinxsidebar a:hover {
       border-bottom: none;
       text-decoration: underline;
       text-underline-offset: 0.3em;
   }

-- 
Thanks,
Nícolas

On Wed, Jun 04, 2025 at 06:05:06PM -0400, Nícolas F. R. A. Prado wrote:
> The only other thing I noticed is that the links in the sidebar still use the
> old style, since they rely on a different CSS selector for some reason:
> 
>   div.sphinxsidebar a {
>     text-decoration: none;
>     border-bottom: 1px dotted #999;
>   }
> 
> That makes it a bit inconsistent style-wise, so I think it'd be sensible to
> update that selector as well to follow suit.

It can be done simply by also applying the same style to aforementioned
selector:

---- >8 ----
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index c9991566f91488..14e1bb9c4e63eb 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -137,8 +137,9 @@ div.language-selection ul li:hover {
     background: #dddddd;
 }
 
-/* Make xrefs more universally visible */
-a.reference, a.reference:hover {
+/* Make xrefs and sidebar links more universally visible */
+a.reference, a.reference:hover,
+div.sphinxsidebar a {
     border-bottom: none;
     text-decoration: underline;
     text-underline-offset: 0.3em;

Thanks.

-- 
An old man doll... just what I always wanted! - Clara