[PATCH v2 0/3] docs: some automarkup improvements

[PATCH v2 0/3] docs: some automarkup improvements

[Jonathan Corbet]

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

[PATCH v2 1/3] docs: automarkup: Remove some Sphinx 2 holdovers

[Jonathan Corbet]

Remove a few declarations that are no longer doing anything now that we
have left Sphinx 2 behind.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
v2: Remove RE_generic_type as suggested by Mauro

 Documentation/sphinx/automarkup.py | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index fd633f7a0bc3..7828aeac92e7 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -22,12 +22,6 @@ from kernel_abi import get_kernel_abi
 #
 RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
 
-#
-# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
-#
-RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
-                             flags=re.ASCII)
-
 #
 # Sphinx 3 uses a different C role for each one of struct, union, enum and
 # typedef
@@ -150,20 +144,12 @@ def markup_func_ref_sphinx3(docname, app, match):
     return target_text
 
 def markup_c_ref(docname, app, match):
-    class_str = {# Sphinx 2 only
-                 RE_function: 'c-func',
-                 RE_generic_type: 'c-type',
-                 # Sphinx 3+ only
-                 RE_struct: 'c-struct',
+    class_str = {RE_struct: 'c-struct',
                  RE_union: 'c-union',
                  RE_enum: 'c-enum',
                  RE_typedef: 'c-type',
                  }
-    reftype_str = {# Sphinx 2 only
-                   RE_function: 'function',
-                   RE_generic_type: 'type',
-                   # Sphinx 3+ only
-                   RE_struct: 'struct',
+    reftype_str = {RE_struct: 'struct',
                    RE_union: 'union',
                    RE_enum: 'enum',
                    RE_typedef: 'type',
-- 
2.49.0

Re: [PATCH v2 1/3] docs: automarkup: Remove some Sphinx 2 holdovers

[Mauro Carvalho Chehab]

Em Wed,  4 Jun 2025 08:36:43 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Remove a few declarations that are no longer doing anything now that we
> have left Sphinx 2 behind.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
> v2: Remove RE_generic_type as suggested by Mauro
> 
>  Documentation/sphinx/automarkup.py | 18 ++----------------
>  1 file changed, 2 insertions(+), 16 deletions(-)
> 
> diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> index fd633f7a0bc3..7828aeac92e7 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -22,12 +22,6 @@ from kernel_abi import get_kernel_abi
>  #
>  RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
>  
> -#
> -# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
> -#
> -RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
> -                             flags=re.ASCII)
> -
>  #
>  # Sphinx 3 uses a different C role for each one of struct, union, enum and
>  # typedef
> @@ -150,20 +144,12 @@ def markup_func_ref_sphinx3(docname, app, match):
>      return target_text
>  
>  def markup_c_ref(docname, app, match):
> -    class_str = {# Sphinx 2 only
> -                 RE_function: 'c-func',
> -                 RE_generic_type: 'c-type',
> -                 # Sphinx 3+ only
> -                 RE_struct: 'c-struct',
> +    class_str = {RE_struct: 'c-struct',
>                   RE_union: 'c-union',
>                   RE_enum: 'c-enum',
>                   RE_typedef: 'c-type',
>                   }
> -    reftype_str = {# Sphinx 2 only
> -                   RE_function: 'function',
> -                   RE_generic_type: 'type',
> -                   # Sphinx 3+ only
> -                   RE_struct: 'struct',
> +    reftype_str = {RE_struct: 'struct',
>                     RE_union: 'union',
>                     RE_enum: 'enum',
>                     RE_typedef: 'type',

[PATCH v2 2/3] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet]

The automarkup code generates markup and a cross-reference link 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.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
v2: Split out the CSS changes into a separate patch

 Documentation/sphinx/automarkup.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 7828aeac92e7..e67eb8e19c22 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -235,8 +235,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 v2 2/3] docs: automarkup: Mark up undocumented entities too

[Mauro Carvalho Chehab]

Em Wed,  4 Jun 2025 08:36:44 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The automarkup code generates markup and a cross-reference link 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.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
> v2: Split out the CSS changes into a separate patch
> 
>  Documentation/sphinx/automarkup.py | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> index 7828aeac92e7..e67eb8e19c22 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -235,8 +235,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

[PATCH v2 3/3] docs: CSS: make cross-reference links more evident

[Jonathan Corbet]

The Sphinx Alabaster theme uses border-bottom to mark reference links; the
result does not render correctly (the underline is missing) in some browser
configurations.  Switch to using the standard text-underline property, and
use text-underline-offset to place that underline below any underscores in
the underlined text.

Suggested-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/sphinx-static/custom.css | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index f4285417c71a..c9991566f914 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -136,3 +136,10 @@ div.language-selection:hover ul {
 div.language-selection ul li:hover {
     background: #dddddd;
 }
+
+/* Make xrefs more universally visible */
+a.reference, a.reference:hover {
+    border-bottom: none;
+    text-decoration: underline;
+    text-underline-offset: 0.3em;
+}
-- 
2.49.0

Re: [PATCH v2 3/3] docs: CSS: make cross-reference links more evident

[Mauro Carvalho Chehab]

Em Wed,  4 Jun 2025 08:36:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The Sphinx Alabaster theme uses border-bottom to mark reference links; the
> result does not render correctly (the underline is missing) in some browser
> configurations.  Switch to using the standard text-underline property, and
> use text-underline-offset to place that underline below any underscores in
> the underlined text.
> 
> Suggested-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

While I didn't test, it looks good enough for me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/sphinx-static/custom.css | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index f4285417c71a..c9991566f914 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -136,3 +136,10 @@ div.language-selection:hover ul {
>  div.language-selection ul li:hover {
>      background: #dddddd;
>  }
> +
> +/* Make xrefs more universally visible */
> +a.reference, a.reference:hover {
> +    border-bottom: none;
> +    text-decoration: underline;
> +    text-underline-offset: 0.3em;
> +}

Re: [PATCH v2 0/3] docs: some automarkup improvements

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

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

Re: [PATCH v2 0/3] docs: some automarkup improvements

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1262 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 0/3] docs: some automarkup improvements

[Jonathan Corbet]

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

Re: [PATCH v2 0/3] docs: some automarkup improvements

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

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