Skip to content

Commit dc03bd4

Browse files
rouiljrouilj
committed
Restyle html documentation
Make doc look better. Try to reduce "wall of dense text" effect. 1) fluid type scale apply to headers along with change to line height 2) increase base line height to 1.5 3) increase proximity of header to the section it leads by reducing bottom margin. 4) add decoration for hovered link. Still have WCAG AA issue with contrast between links and base text 5) remove most pure white and pure black from document to reduce eye strain 6) in side nav reduce indent from 2em to 1em to better fit labels 7) use same styles for web site doc and release doc on local disk 8) a 'p' inside a 'table' now aligns with top of table cell by removing top margin. 9) in web doc, highlight the current section
1 parent 9ab437a commit dc03bd4

File tree

2 files changed

+381
-85
lines changed

2 files changed

+381
-85
lines changed

‎doc/_static/style.css‎

Lines changed: 188 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,86 @@
11
/* layout*/
2+
3+
/* Set up fluid type scale. Major third for smaller screens
4+
and perfect fourth for larger screens.
5+
Allow override using --font-level-X.
6+
7+
https://set.studio/some-simple-ways-to-make-content-look-good/
8+
*/
9+
10+
:root {
11+
--_font-level-0: var(--font-level-0,
12+
clamp(1rem,
13+
0.96rem + 0.22vw,
14+
1.13rem)
15+
);
16+
--_font-level-1: var(--font-level-1,
17+
clamp(
18+
1.25 * var(--_font-level-0),
19+
1.16rem + 0.43vw,
20+
1.5rem)
21+
);
22+
--_font-level-2: var(--font-level-2,
23+
clamp(
24+
1.25 * var(--_font-level-1),
25+
1.41rem + 0.76vw,
26+
2rem)
27+
);
28+
--_font-level-3: var(--font-level-3,
29+
clamp(
30+
1.25 * var(--_font-level-2),
31+
1.71rem + 1.24vw,
32+
2.66rem)
33+
);
34+
--_font-level-4: var(--font-level-4,
35+
clamp(
36+
1.25 * var(--_font-level-3),
37+
2.05rem + 1.93vw,
38+
3.55rem)
39+
);
40+
}
41+
42+
h1, h2, h3, h4, h5, h6 {
43+
line-height: 1.25;
44+
/* Larger spacing before header and smaller after to make
45+
header part of following section */
46+
margin-block-end: 0.3em;
47+
}
48+
49+
h1 {
50+
font-size: var(--_font-level-4);
51+
}
52+
53+
/* remove whitespace at top of main column */
54+
main h1 { margin-block-start: 0; }
55+
56+
h2 {
57+
font-size: var(--_font-level-3);
58+
}
59+
60+
h3 {
61+
font-size: var(--_font-level-2);
62+
}
63+
64+
h4 {
65+
font-size: var(--_font-level-1);
66+
}
67+
68+
/* snug header up to first paragraph of it's section. */
69+
:is(h1,h2,h3,h4,h5,h6) + p {
70+
margin-block-start: 0;
71+
}
72+
273
body
374
{
75+
background-color: #f5f5f5;
76+
color: #222;
477
font-family: sans-serif, Arial, Helvetica;
5-
background-color: white;
6-
color: #333;
78+
font-size: var(--_font-level-0);
779
margin:0;
880
padding: 0 3em 0 14em;
981
}
82+
83+
/* -14em is size of table of contents/nav */
1084
body > .header { margin: 0 0 0 -14em;}
1185
body > .header div.label { font-size: 2em; font-weight: bold; margin: 0.67em 0 0.67em 1em;}
1286
body > .footer { margin: 1em 0 1em -14em; clear:both;}
@@ -18,40 +92,86 @@ body > .navigation
1892
}
1993
body > .content
2094
{
21-
width: 100%;
2295
margin: 0;
96+
width: 100%;
2397
}
2498
body > .header > #searchbox { position: absolute; right: 1em; top: 1em;}
99+
body > .content > #subnav { position: absolute; right: 1.5em; top: 6em;}
100+
101+
/* limit width of main column to 65 characters. On wider screens can
102+
be 100+ chars: too wide */
103+
main {
104+
max-width: 65ch;
105+
line-height: calc(1.5 * 1em);
106+
}
25107

26108
/* style */
27109

28110
:link { color: #bb0000; text-decoration: none;}
111+
:link:hover {text-decoration: underline;}
29112
:visited { color: #770000; text-decoration: none;}
30113
a.toc-backref { color: #000000; }
31114

32115
.header h1 { margin-left: 1em; }
33116

34-
body
117+
.menu { padding: 0; margin-right: 1em;}
118+
.menu ul
35119
{
36-
font-family: sans-serif, Arial, Helvetica;
37-
background-color: #f5f5f5;
38-
color: #333;
120+
padding: 0;
121+
margin: 0;
39122
}
40-
41-
.menu
123+
.menu li
42124
{
43-
margin-right: 1em;
44-
padding: 2pt;
125+
margin: 5pt 0;
126+
}
127+
.menu > ul > li > *
128+
{
129+
display: block;
130+
padding: 2pt 2pt 2pt 10pt;
45131
border: solid thin #dadada;
46132
background-color:#ffffff;
47133
}
48-
.menu ul { list-style-type:none; padding: 0;}
49-
.menu ul ul { padding-left: 1em;}
50-
.menu li { border-top: solid thin #dadada;}
51-
.menu li:first-child { border-top: none;}
134+
.menu > ul > li.current > *
135+
{
136+
background-color:#dddddd;
137+
}
52138

53-
/* related */
139+
.menu ul li:first-child { margin-top:0;}
140+
.menu ul { list-style-type:none;}
54141

142+
/* sub-menus are indented */
143+
.menu > ul > li > ul,
144+
.menu > ul > li.current > ul
145+
{
146+
border:none;
147+
background-color: inherit;
148+
}
149+
.menu ul ul
150+
{
151+
margin-left: 1em;
152+
font-size: smaller;
153+
}
154+
155+
/* sub-menu items draw a separator */
156+
.menu ul ul > li
157+
{
158+
margin: 0;
159+
padding: 0;
160+
border: none;
161+
border-top: solid thin #dadada;
162+
background-color: inherit;
163+
}
164+
.menu ul ul > li:first-child
165+
{
166+
border-top: none;
167+
}
168+
169+
.menu ul li.toctree-l2.current {
170+
background-color: #dddddd;
171+
pading-block: 0.25em;
172+
}
173+
174+
/* related */
55175
div.related
56176
{
57177
width: 100%;
@@ -79,14 +199,18 @@ div.related li.right
79199
{
80200
font-size: small;
81201
text-align: center;
82-
color: lightgrey;
202+
color: black;
203+
}
204+
205+
.footer img {
206+
vertical-align: middle;
83207
}
84208

85209
.content
86210
{
87211
padding: 1em;
88212
border: solid thin #dadada;
89-
background-color: #ffffff;
213+
background-color: #f7f7f7;
90214
}
91215

92216
/* This is a little hack to inject a 'news' block into the title
@@ -109,16 +233,36 @@ table
109233
background-color: #fafafa;
110234
}
111235

112-
a.headerlink {
113-
font-size: 0.8em;
114-
margin-left: 0.3em;
115-
color: #c99;
236+
table:has(caption) {
237+
margin-block: 1em;
116238
}
117239

240+
table caption { font-weight: bold; font-size: smaller; }
241+
118242
table.footnote {
119243
font-size: calc(1em - 1pt);
120244
}
121245

246+
td {
247+
/* pull text away from borders */
248+
padding-inline: 0.5em;
249+
}
250+
251+
td > p {
252+
/* remove top margin on a p inside table cell so that
253+
columns with paragraphs align at top of cell rather
254+
than leaving a blank margin */
255+
margin-block-start: 0px;
256+
}
257+
258+
input, textarea { border-width: 1px; }
259+
260+
a.headerlink {
261+
font-size: 0.8em;
262+
margin-left: 0.3em;
263+
color: #c99;
264+
}
265+
122266
div.admonition {
123267
padding-inline: 1em;
124268
padding-block: 0.25em;
@@ -147,3 +291,25 @@ div.admonition.caution p.admonition-title {
147291

148292
dt { font-weight: bold; margin-block-start: 1em;}
149293
dd p.first { margin-block-start: 0; }
294+
295+
#skiplink { display: block;
296+
margin-block-start: 1em;
297+
margin-inline-start: 1em;}
298+
#skiplink a {
299+
/* force stuff for screenreader off screen */
300+
position:absolute;
301+
left:-10000px;
302+
top:auto;
303+
width:1px;
304+
height:1px;
305+
overflow:hidden;
306+
padding: 0 0.75em;
307+
font-weight: bold;
308+
}
309+
#skiplink a:focus { position: static;
310+
width: auto;
311+
height: auto; }
312+
313+
/* remove solid black border when focus is around the main section
314+
due to activation of skip-link. Page jumps there, that's enough. */
315+
#main:focus-visible {outline: none;}

0 commit comments

Comments
 (0)