Skip to content

Commit 6b90563

Browse files
PLeVasseurPLeVasseur
authored
Update formatting to make guidelines more legible (#289)
* chore: fix text wrapping * fix: make paragraphs break up appropriately
1 parent 29d81b1 commit 6b90563

2 files changed

Lines changed: 214 additions & 0 deletions

File tree

‎src/_static/custom.css‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
/* SPDX-License-Identifier: MIT OR Apache-2.0
2+
SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors */
3+
4+
/* ==========================================================================
5+
Custom styles for Safety-Critical Rust Coding Guidelines
6+
========================================================================== */
7+
8+
/* --------------------------------------------------------------------------
9+
1. Fix parent containers that clip content
10+
11+
RTD theme and sphinx-needs may have overflow:hidden on containers.
12+
We need to allow content to either wrap (text) or scroll (code).
13+
-------------------------------------------------------------------------- */
14+
15+
/* Remove any hidden overflow from content containers */
16+
.wy-nav-content,
17+
.rst-content,
18+
.document,
19+
article,
20+
section,
21+
.section {
22+
overflow: visible !important;
23+
}
24+
25+
/* Sphinx-needs containers - these are the gray boxes */
26+
.need,
27+
.needs_container,
28+
div[class*="need_"],
29+
table.need,
30+
.needs_table_container {
31+
overflow: visible !important;
32+
max-width: 100% !important;
33+
box-sizing: border-box !important;
34+
}
35+
36+
/* The content wrapper inside needs */
37+
.needs_content,
38+
.need_content,
39+
td.needs_content,
40+
.needs_body {
41+
overflow: visible !important;
42+
max-width: 100% !important;
43+
box-sizing: border-box !important;
44+
}
45+
46+
/* --------------------------------------------------------------------------
47+
2. Force text wrapping everywhere
48+
-------------------------------------------------------------------------- */
49+
50+
/* Apply aggressive word wrapping to all text containers */
51+
.rst-content p,
52+
.rst-content li,
53+
.rst-content dd,
54+
.rst-content td,
55+
.rst-content th,
56+
.rst-content div,
57+
.needs_content,
58+
.needs_content p,
59+
.need_content,
60+
.need_content p,
61+
td.needs_content,
62+
td.needs_content p {
63+
word-wrap: break-word !important;
64+
overflow-wrap: break-word !important;
65+
word-break: break-word !important;
66+
max-width: 100% !important;
67+
box-sizing: border-box !important;
68+
}
69+
70+
/* Sphinx-needs metadata fields */
71+
.needs_meta,
72+
.needs_meta span,
73+
[class*="needs_"] {
74+
word-wrap: break-word !important;
75+
overflow-wrap: break-word !important;
76+
white-space: normal !important;
77+
}
78+
79+
/* Keep individual links together but allow wrapping between them */
80+
.needs_data a {
81+
white-space: nowrap;
82+
display: inline;
83+
}
84+
85+
/* --------------------------------------------------------------------------
86+
3. Code blocks - must scroll, never wrap or clip
87+
-------------------------------------------------------------------------- */
88+
89+
/* The wrapper div needs to scroll */
90+
div.highlight,
91+
.rst-content div.highlight,
92+
.highlight,
93+
.rust-example-container {
94+
overflow-x: auto !important;
95+
overflow-y: visible !important;
96+
max-width: 100% !important;
97+
box-sizing: border-box !important;
98+
}
99+
100+
/* Code blocks need to scroll, not wrap */
101+
pre,
102+
div.highlight pre,
103+
.rst-content div.highlight pre,
104+
.highlight pre,
105+
.rust-example-container pre,
106+
.rust-example-code {
107+
white-space: pre !important;
108+
overflow-x: auto !important;
109+
overflow-y: visible !important;
110+
word-wrap: normal !important;
111+
overflow-wrap: normal !important;
112+
max-width: 100% !important;
113+
box-sizing: border-box !important;
114+
}
115+
116+
/* Code inside needs containers specifically */
117+
.need pre,
118+
.needs_container pre,
119+
.needs_content pre,
120+
td.needs_content pre,
121+
.need div.highlight,
122+
.needs_container div.highlight,
123+
.needs_content div.highlight,
124+
td.needs_content div.highlight {
125+
overflow-x: auto !important;
126+
max-width: 100% !important;
127+
box-sizing: border-box !important;
128+
}
129+
130+
.need div.highlight pre,
131+
.needs_container div.highlight pre,
132+
.needs_content div.highlight pre,
133+
td.needs_content div.highlight pre {
134+
white-space: pre !important;
135+
overflow-x: auto !important;
136+
word-wrap: normal !important;
137+
}
138+
139+
/* --------------------------------------------------------------------------
140+
4. Inline code
141+
-------------------------------------------------------------------------- */
142+
143+
/* Allow inline code to break in flowing text */
144+
p code,
145+
li code,
146+
td code,
147+
.rst-content p code,
148+
.rst-content li code,
149+
code.literal {
150+
white-space: normal !important;
151+
word-break: break-word !important;
152+
}
153+
154+
/* --------------------------------------------------------------------------
155+
5. Paragraph spacing inside sphinx-needs content
156+
157+
Ensure proper visual separation between paragraphs in guideline content.
158+
-------------------------------------------------------------------------- */
159+
160+
/* Add margin between paragraphs in needs content */
161+
/* The actual class is "need content" (two classes), not "needs_content" */
162+
.need.content p,
163+
td.need.content p,
164+
.needs_content p,
165+
td.needs_content p,
166+
.need_content p {
167+
margin-bottom: 1em !important;
168+
}
169+
170+
/* But not on the last paragraph */
171+
.need.content p:last-child,
172+
td.need.content p:last-child,
173+
.needs_content p:last-child,
174+
td.needs_content p:last-child,
175+
.need_content p:last-child {
176+
margin-bottom: 0 !important;
177+
}
178+
179+
/* Also ensure lists have proper spacing */
180+
.need.content ul,
181+
.need.content ol,
182+
td.need.content ul,
183+
td.need.content ol,
184+
.needs_content ul,
185+
.needs_content ol {
186+
margin-top: 0.5em !important;
187+
margin-bottom: 1em !important;
188+
}
189+
190+
/* --------------------------------------------------------------------------
191+
6. Table fixes for sphinx-needs (uses tables internally)
192+
-------------------------------------------------------------------------- */
193+
194+
table.need,
195+
.needs_table,
196+
table[class*="need"] {
197+
table-layout: fixed !important;
198+
width: 100% !important;
199+
max-width: 100% !important;
200+
}
201+
202+
table.need td,
203+
table.need th,
204+
.needs_table td,
205+
.needs_table th {
206+
word-wrap: break-word !important;
207+
overflow-wrap: break-word !important;
208+
max-width: 100% !important;
209+
}

‎src/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,3 +213,8 @@
213213
html_theme = "sphinx_rtd_theme"
214214
html_static_path = ["_static"]
215215
templates_path = ['_templates']
216+
217+
# Custom CSS files to include
218+
html_css_files = [
219+
'custom.css',
220+
]

0 commit comments

Comments
 (0)