Skip to content

Commit 68483d4

Browse files
jarrodmillmanjarrodmillman
authored
Use pydata-sphinx-theme admonition styling (#301)
* Add pydata-sphinx-theme admonition styling * No bootstrap * Add pydata-sphinx-theme colors * Add shortcodes and test * Use bulma box-shadow instead of bootstraps * Use box-shadow
1 parent 171827d commit 68483d4

14 files changed

Lines changed: 1317 additions & 2 deletions

File tree

‎assets/theme-css/pst/abstracts/_accessibility.scss‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// loading the math module
2+
@use "sass:math";
3+
4+
/**
5+
* Get color combinations that meet a minimum contrast ratio as per WCAG 2
6+
*/
7+
// @param {color} $bg - Background color of the element
8+
// @param {color} optional $target-color-contrast-dark $target-color-contrast-light - Target text colors, defaul to our
9+
// $foundation-black and $foundation-white colors
10+
// @return {color} $max-ratio-color - The color that has the highest contrast ratio
11+
//
12+
@function a11y-combination(
13+
$bg,
14+
$target-color-contrast-dark: $foundation-black,
15+
$target-color-contrast-light: $foundation-white,
16+
$min-contrast-ratio: $min-contrast-ratio-4
17+
) {
18+
// will test against the specified foreground colors
19+
$foregrounds: $target-color-contrast-light, $target-color-contrast-dark;
20+
$max-ratio: 0;
21+
$max-ratio-color: null;
22+
23+
@each $fg in $foregrounds {
24+
$contrast-ratio: get-contrast-ratio($bg, $fg);
25+
@if $contrast-ratio >= $min-contrast-ratio {
26+
@return $fg;
27+
} @else if $contrast-ratio > $max-ratio {
28+
$max-ratio: $contrast-ratio;
29+
$max-ratio-color: $fg;
30+
}
31+
}
32+
@warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$bg}...";
33+
34+
@return $max-ratio-color;
35+
}
36+
37+
@function get-contrast-ratio($bg, $foreground) {
38+
$l1: luminance($bg);
39+
$l2: luminance($foreground);
40+
41+
// return the relative contrast ratio
42+
@if $l1 > $l2 {
43+
@return math.div(($l1 + 0.05), ($l2 + 0.05));
44+
} @else {
45+
@return math.div(($l2 + 0.05), ($l1 + 0.05));
46+
}
47+
}
48+
49+
// Return WCAG2.1 relative luminance
50+
// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
51+
// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
52+
//
53+
@function luminance($target-color) {
54+
$rgb-col: (
55+
"r": red($target-color),
56+
"g": green($target-color),
57+
"b": blue($target-color),
58+
);
59+
60+
@each $channel, $value in $rgb-col {
61+
// here we get RsRGB, GsRGB, and BsRGB
62+
@if math.div($value, 255) <=0.03928 {
63+
$rgb-col: map-merge(
64+
$rgb-col,
65+
(
66+
$channel: math.div(math.div($value, 255), 12.92),
67+
)
68+
);
69+
} @else {
70+
$rgb-col: map-merge(
71+
$rgb-col,
72+
(
73+
$channel:
74+
math.pow(math.div((math.div($value, 255) + 0.055), 1.055), 2.4),
75+
)
76+
);
77+
}
78+
}
79+
80+
@return (
81+
0.2126 * map-get($rgb-col, "r") + 0.7152 * map-get($rgb-col, "g") + 0.0722 *
82+
map-get($rgb-col, "b")
83+
);
84+
}

‎assets/theme-css/pst/abstracts/_all.scss‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@import "accessibility";
2+
@import "color";
3+
@import "mixins";
4+
@import "links";

‎assets/theme-css/pst/abstracts/_color.scss‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
/**
2+
* Miscellaneous color functions and mixins
3+
**/
4+
5+
// loading the math module
6+
@use "sass:math";
7+
8+
// Set background color from a color variable
9+
//
10+
@mixin background-from-color-variable($color-variable) {
11+
&:before {
12+
content: "";
13+
width: 100%;
14+
height: 100%;
15+
position: absolute;
16+
left: 0;
17+
top: 0;
18+
background-color: var(#{$color-variable});
19+
z-index: -1;
20+
// So that hovering over the text within background is still possible.
21+
// Otherwise the background overlays the text and you cannot click or select easily.
22+
// ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
23+
pointer-events: none;
24+
}
25+
}
26+
27+
/**
28+
* Function to get items from nested maps
29+
*/
30+
// @param {Map} $map - Map
31+
// @param {Arglist} $keys - Keys to fetc
32+
// @return {*}
33+
@function map-deep-get($map, $keys...) {
34+
@each $key in $keys {
35+
$map: map-get($map, $key);
36+
}
37+
@return $map;
38+
}
39+
40+
/**
41+
* Function to check if the color needs converting to a "color" type
42+
* if it is a string we cannot use other color manipulation functions
43+
* It is used to create the sphinx-design colours as these are often interpolated
44+
*/
45+
// @param {String/Color} $color - Color definition from map
46+
// @return {Color} - Color type (in hex)
47+
@function check-color($color) {
48+
@if type-of($color) == string {
49+
$color: from-hex($color);
50+
}
51+
@return $color;
52+
}
53+
54+
/**
55+
* Function to convert the string representation of a color to a color type (hex)
56+
*/
57+
// @param {String} $string - String representation of a color
58+
@function from-hex($string) {
59+
$string-lower: to-lower-case($string);
60+
$r: "";
61+
$g: "";
62+
$b: "";
63+
$hex: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "a" "b" "c" "d" "e" "f";
64+
$length: str-length($string);
65+
$max: if($length == 4, 1, 2);
66+
67+
// Check for length accuracy
68+
@if $length != 4 and $length != 7 {
69+
@return $string;
70+
}
71+
72+
// Loop from the second character (omitting #)
73+
@for $i from 2 through $length {
74+
$c: str-slice($string-lower, $i, $i);
75+
76+
// If wrong character, return
77+
@if index($hex, $c) == null {
78+
@return $string;
79+
}
80+
81+
@if str-length($r) < $max {
82+
$r: $r + $c;
83+
} @else if str-length($g) < $max {
84+
$g: $g + $c;
85+
} @else if str-length($b) < $max {
86+
$b: $b + $c;
87+
}
88+
}
89+
90+
@if $length == 4 {
91+
$r: $r + $r;
92+
$g: $g + $g;
93+
$b: $b + $b;
94+
}
95+
96+
@return rgb(_hex-to-dec($r), _hex-to-dec($g), _hex-to-dec($b));
97+
}
98+
99+
@function _hex-to-dec($string) {
100+
$hex: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "a" "b" "c" "d" "e" "f";
101+
$string: to-lower-case($string);
102+
$length: str-length($string);
103+
104+
$dec: 0;
105+
@for $i from 1 through $length {
106+
$factor: 1 + (15 * ($length - $i));
107+
$index: index($hex, str-slice($string, $i, $i));
108+
$dec: $dec + $factor * ($index - 1);
109+
}
110+
111+
@return $dec;
112+
}

‎assets/theme-css/pst/abstracts/_links.scss‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
/**
2+
* Consistent styling for links
3+
**/
4+
5+
// Define some useful variables for links styling consistency
6+
//
7+
// Thickness of the underline for links
8+
// the default will be either:
9+
// - 1px
10+
// - 0.0625rem if it's thicker than 1px because the user has changed the text
11+
// size in their browser
12+
$link-underline-thickness: unquote("max(1px, .0625rem)") !default;
13+
// Offset of link underlines from text baseline
14+
// The default is 3px expressed as ems, as calculated against the default body
15+
// font size (on desktop).
16+
$link-underline-offset: 0.1578em !default;
17+
// Thickness of link underlines in hover state
18+
// The default for each link will be the thickest of the following:
19+
// - 3px
20+
// - 0.1875rem, if it's thicker than 3px because the user has changed the text
21+
// size in their browser
22+
// - 0.12em (relative to the link's text size)
23+
$link-hover-decoration-thickness: unquote("max(3px, .1875rem, .12em)") !default;
24+
25+
// Ensures links have an underline decoration by default - needed to meet
26+
// WCAG SC 1.4.1
27+
@mixin link-decoration {
28+
text-decoration: underline;
29+
30+
@if $link-underline-thickness {
31+
text-decoration-thickness: $link-underline-thickness;
32+
}
33+
34+
@if $link-underline-offset {
35+
text-underline-offset: $link-underline-offset;
36+
}
37+
}
38+
39+
// Ensures links have an underline decoration on hover - distinct from the
40+
// default behaviour
41+
@mixin link-decoration-hover {
42+
@if $link-hover-decoration-thickness {
43+
text-decoration-thickness: $link-hover-decoration-thickness;
44+
// Disable ink skipping on underlines on hover. Browsers haven't
45+
// standardised on this part of the spec yet, so set both properties
46+
text-decoration-skip-ink: none; // Chromium, Firefox
47+
text-decoration-skip: none; // Safari
48+
}
49+
}
50+
51+
// Simple hover style - can be used alone or in conjunction with other mixins
52+
// Add the text underline and change in thickness on hover
53+
@mixin link-style-hover {
54+
&:hover {
55+
@include link-decoration;
56+
@include link-decoration-hover;
57+
color: var(--pst-color-link-hover);
58+
}
59+
}
60+
61+
// Default link styles
62+
//
63+
// Defines: default unvisited, visited, hover, and active.
64+
// TODO: @trallard to improve focus styles in subsequent PR
65+
@mixin link-style-default {
66+
// So that really long links don't spill out of their container
67+
word-wrap: break-word;
68+
69+
color: var(--pst-color-link);
70+
@include link-decoration;
71+
72+
&:hover {
73+
color: var(--pst-color-link-hover);
74+
@include link-decoration-hover;
75+
}
76+
77+
// TODO: @trallard to add active styles in subsequent PR
78+
&:active {
79+
color: var(--pst-color-link);
80+
}
81+
82+
// Visited should still be hoverable
83+
&:visited {
84+
color: var(--pst-color-link);
85+
&:hover {
86+
color: var(--pst-color-link-hover);
87+
}
88+
}
89+
@include focus-indicator;
90+
}
91+
92+
// Text link styles
93+
//
94+
// Makes links use the muted text colour and removes the underline.
95+
// Use this mixin for navigation bar links.
96+
@mixin link-style-text {
97+
color: var(--pst-color-text-muted);
98+
text-decoration: none;
99+
100+
&:hover {
101+
color: var(--pst-color-link-hover);
102+
@include link-decoration;
103+
@include link-decoration-hover;
104+
}
105+
@include focus-indicator;
106+
}
107+
108+
// Sidebar and TOC links
109+
//
110+
// Makes links use the muted text colour and removes the underline.
111+
// Use this mixin for navigation the primary sidebar and table of contents.
112+
// Active and hover should work together rather than one overriding the other.
113+
@mixin link-sidebar {
114+
color: var(--pst-color-text-muted);
115+
text-decoration: none;
116+
117+
&:hover {
118+
text-decoration: underline;
119+
background-color: transparent;
120+
color: var(--pst-color-link-hover);
121+
@include link-decoration-hover;
122+
}
123+
124+
// TODO: @trallard to update active styles in subsequent PR
125+
&:active {
126+
color: var(--pst-color-link-hover);
127+
}
128+
}
129+
130+
// Sidebar current page link styles
131+
//
132+
// Adds a vertical line on the left hand side of the link to indicate that
133+
// it's the current page. Note this is distinct from an active state.
134+
// Used on the primary sidebar and the TOC.
135+
// We want the side box shadow to have the same thickness as the hover underline
136+
@mixin link-sidebar-current {
137+
font-weight: 600;
138+
color: var(--pst-color-primary);
139+
@if $link-hover-decoration-thickness {
140+
box-shadow: inset
141+
$link-hover-decoration-thickness
142+
0px
143+
0px
144+
var(--pst-color-primary);
145+
}
146+
}
147+
148+
// Navigation bar current page link styles
149+
//
150+
// Adds a bottom underline, this leaves enough space for the hover state without
151+
// cluttering the navbar.
152+
// We want the side box shadow to have the same thickness as the hover underline
153+
@mixin link-navbar-current {
154+
font-weight: 600;
155+
color: var(--pst-color-primary);
156+
@if $link-hover-decoration-thickness {
157+
border-bottom: $link-hover-decoration-thickness
158+
solid
159+
var(--pst-color-primary);
160+
}
161+
}
162+
163+
// Navigation bar icon links hover styles
164+
//
165+
// Adds a bottom box-shadow - since there is no text we cannot use text-decoration
166+
// We want the side box shadow to have the same thickness as the hover underline
167+
@mixin icon-navbar-hover {
168+
&:hover {
169+
color: var(--pst-color-link-hover);
170+
@if $link-hover-decoration-thickness {
171+
box-shadow: 0px
172+
$link-hover-decoration-thickness
173+
0px
174+
var(--pst-color-link-hover);
175+
}
176+
}
177+
}
178+
179+
// Focus indicator
180+
@mixin focus-indicator {
181+
&:focus-visible {
182+
outline: 2px solid var(--pst-color-accent);
183+
}
184+
}

0 commit comments

Comments
 (0)