From 5224283ea9bd912fd79915f7d6f36cfd6d99bf1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Tue, 16 Dec 2025 18:33:03 +0100 Subject: [PATCH] doc: css: re-style definition lists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Definition lists are key for explaining terminology, and making them visually cohesive can help the reader better scan information. This change introduces a distinct visual hierarchy by: - Adding a vertical border to group the list items. - Highlighting terms (dt) with a background color and rounded corners. - Adding decorative indicators (bullets) to separate entries clearly. The new style is also intentionally more visually distinct so that _incorrect_ usage of definition lists (usually due to bad indentation) can be more easily detected as it won't look good when not used for things meant to be "definition lists" :) Signed-off-by: Benjamin Cabé --- doc/_static/css/custom.css | 113 ++++++++----------------------------- 1 file changed, 25 insertions(+), 88 deletions(-) diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index 5f7cc6e3d9a..0fb4f02a70c 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -121,94 +121,6 @@ hr, border-color: var(--hr-color); } -/* JavaScript documentation directives */ -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list) > dt { - background-color: var(--admonition-note-background-color); - border-color: var(--admonition-note-title-background-color); - color: var(--admonition-note-color); -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl dt { - background-color: transparent; - border-color: transparent; - color: var(--footer-color); -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).attribute dt { - font-weight: 600; - padding: 0 8px; - margin-bottom: 1px; - width: 100%; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class > dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function > dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method > dt, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).attribute > dt { - font-family: var(--monospace-font-family); - font-variant-ligatures: none; - font-size: 90%; - font-weight: normal; - margin-bottom: 16px; - padding: 6px 8px; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-prename.descclassname { - color: var(--highlight-type2-color); - font-weight: normal; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name.descname { - color: var(--highlight-function-color); - font-weight: 700; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-paren, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional { - color: var(--highlight-operator-color) !important; - font-weight: normal; - padding: 0 2px; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional { - font-style: italic; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-param, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > em, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt > em, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt > em { - color: var(--code-literal-color); - font-style: normal; - padding: 0 4px; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .k { - font-style: normal; -} -html.writer-html5 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { - border-top-color: var(--highlight-background-emph-color); - background: var(--highlight-background-color); -} -html.writer-html5 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { - border-left-color: var(--highlight-background-emph-color); - background: var(--highlight-background-color); -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-param, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > .optional ~ em, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt > .optional ~ em, -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt > .optional ~ em { - color: var(--highlight-number-color); - font-style: italic; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > em.property { - color: var(--highlight-keyword-color); -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt a.headerlink { - color: var(--link-color) !important; -} -html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt a.headerlink:visited { - color: var(--link-color-visited); -} -html.writer-html5 .rst-content dl.field-list > dd strong { - font-family: var(--monospace-font-family); - font-variant-ligatures: none; -} footer, #search-results .context { @@ -607,6 +519,31 @@ kbd, .kbd, font-weight: 100; } +/* Definition lists */ +.rst-content dl { + border-left: 4px solid var(--admonition-note-background-color); +} + +.rst-content dl:not(.field-list) > dt { + position: relative; + padding-left: 1rem; + line-height: 1.8rem; + background: var(--highlight-background-color); + border-radius: 0 16px 16px 0; +} + +.rst-content dl:not(.field-list) > dt::before { + content: ''; + position: absolute; + left: -10px; + top: 6px; + width: 16px; + height: 16px; + background: var(--admonition-note-title-background-color); + border-radius: 50%; + border: 4px solid var(--content-background-color); +} + /* Buttons */ .btn-neutral {