docs: some automarkup improvements
Subsystems (2)
Jonathan Corbet
maintainerv2 cover docs: some automarkup improvements
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(-)
Signature · 1 line
2.49.0
Jonathan Corbet
maintainerPATCH v2 1/3 docs: automarkup: Remove some Sphinx 2 holdovers
Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind.
---
v2: Remove RE_generic_type as suggested by Mauro
Documentation/sphinx/automarkup.py | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-)
Documentation/sphinx/automarkup.py +2 -16
@@ -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',
Signature · 1 line
2.49.0
Re: [PATCH v2 1/3] docs: automarkup: Remove some Sphinx 2 holdovers
Em Wed, 4 Jun 2025 08:36:43 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 4 lines
Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind.
Signed-off-by Jonathan Corbet <[email protected]>
Quoted 46 lines
---
v2: RemoveRE_generic_typeas suggested by MauroDocumentation/sphinx/automarkup.py | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-)Documentation/sphinx/automarkup.py +2
-16@@ -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',
Jonathan Corbet
maintainerPATCH v2 2/3 docs: automarkup: Mark up undocumented entities too
In reply to Jonathan CorbetThe 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.
---
v2: Split out the CSS changes into a separate patch
Documentation/sphinx/automarkup.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)
Documentation/sphinx/automarkup.py +7 -2
@@ -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
Signature · 1 line
2.49.0
Re: [PATCH v2 2/3] docs: automarkup: Mark up undocumented entities too
Em Wed, 4 Jun 2025 08:36:44 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 9 lines
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 <[email protected]>
Quoted 26 lines
---
v2: Split out the CSS changes into a separate patchDocumentation/sphinx/automarkup.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)Documentation/sphinx/automarkup.py +7
-2@@ -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
Jonathan Corbet
maintainerPATCH v2 3/3 docs: CSS: make cross-reference links more evident
In reply to Jonathan CorbetThe 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.
--- Documentation/sphinx-static/custom.css | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/sphinx-static/custom.css +7 -0
@@ -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; +}
Signature · 1 line
2.49.0
Re: [PATCH v2 3/3] docs: CSS: make cross-reference links more evident
Em Wed, 4 Jun 2025 08:36:45 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 8 lines
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 <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>
While I didn't test, it looks good enough for me.
Quoted 19 lines
--- Documentation/sphinx-static/custom.css | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/sphinx-static/custom.css +7
-0@@ -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; +}
Quoted 7 lines · 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
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,
Thanks,
Nícolas
Quoted 10 lines · Nícolas F. R. A. Prado
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 ----
Documentation/sphinx-static/custom.css +3 -2
@@ -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.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Jonathan Corbet
maintainerQuoted 10 lines · Nícolas F. R. A. Prado
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
Quoted 27 lines · Jonathan Corbet
Quoted 5 lines · Nícolas F. R. A. Prado
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:Quoted 8 lines
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;
}
Quoted 3 lines
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;
}Signature · 2 lines
Thanks, Nícolas