Skip to content

Commit c530de5

Browse files
acoultonacoulton
authored
Merge pull request #196 from acoulton/docs-theme
Modernise / redesign the docs theme
2 parents ff2f435 + 089f8ef commit c530de5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

94 files changed

+948
-1971
lines changed

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ jobs:
1717
- uses: actions/checkout@v4
1818

1919
- name: Run build command
20-
run: docker compose run --rm read-the-docs-builder
20+
run: docker compose run --rm read-the-docs-builder build
2121

2222
- name: Check build
2323
run: cat _build/html/guides.html

‎README.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,17 +39,34 @@ built version.
3939
## Building locally
4040

4141
For more significant changes, you may want to build the full docs site locally. For this, you will need python, sphinx
42-
and the relevant dependencies. The easiest solution may be to use a temporary docker container. In this repository you will
43-
find a `Dockerfile` and a `docker-compose.yml` file that will let you do that easily
42+
and the relevant dependencies.
43+
44+
The easiest solution may be to use a temporary docker container. In this repository you will find a `Dockerfile`
45+
and a `docker-compose.yml` file that will let you do that easily.
46+
47+
You can run a one-time build:
4448

4549
```bash
4650
# Launch a docker container with the right dependencies and run the site build command
4751
# This will build the container if needed, using the Dockerfile
48-
docker compose run --rm read-the-docs-builder
52+
docker compose run --rm read-the-docs-builder build
4953

5054
# The docs will be generated into _build/html
5155
# Check the CLI output for any errors
5256
```
5357

58+
Or you can serve the docs locally over HTTP and rebuild them automatically as you make changes:
59+
60+
```bash
61+
# By default, the docs will be served on port 8000 but you can specify a custom port
62+
SPHINX_PORT=8129 docker compose up --remove-orphans
63+
64+
# Browse to http://localhost:8129 (or your specified SPHINX_PORT) to see the built docs.
65+
# They will re-build and refresh in the browser each time you save changes.
66+
67+
# The docs will also be generated statically into _build/html
68+
```
69+
70+
5471
If you encounter problems, start by looking at the logs of the latest build on Read the Docs to see the commands that
5572
were executed. It's possible that this README has got out of date with later changes to the build process.

‎_theme/css/admonition.css‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/*
2+
* Apply custom colour scheme to admonitions
3+
* @todo could Wagtail support this as CSS variables directly?
4+
*/
5+
6+
.admonition {
7+
/* fallback for old browsers (they already get a border and drop shadow) */
8+
background-color: transparent !important;
9+
/*
10+
* the panel body should be a subdued version of the title background. This can be done
11+
* by mixing with transparent, which will lighten the colour in light mode, and darken
12+
* it in dark.
13+
*/
14+
background-color: color-mix(in oklab, var(--bh-admonition-bg) 15%, transparent) !important;
15+
16+
> .admonition-title {
17+
background-color: var(--bh-admonition-bg) !important;
18+
color: var(--bh-admonition-title-color) !important;
19+
}
20+
21+
&.hint,
22+
&.note {
23+
--bh-admonition-bg: var(--bh-adm-hint-bg);
24+
}
25+
26+
&.important,
27+
&.seealso,
28+
&.tip {
29+
--bh-admonition-bg: var(--bh-adm-tip-bg);
30+
}
31+
32+
&.caution,
33+
&.warning,
34+
&.attention {
35+
--bh-admonition-bg: var(--bh-adm-warning-bg);
36+
}
37+
38+
&.danger,
39+
&.error {
40+
--bh-admonition-bg: var(--bh-adm-danger-bg);
41+
}
42+
43+
44+
}

‎_theme/css/behat-docs.css‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/*
2+
* Behat custom documentation CSS
3+
* These CSS files are compiled together and minified with lightningcss
4+
* Do not add individual styles in this file, group them together
5+
*/
6+
@import "colours-brand.css";
7+
@import "colours-light.css";
8+
@import "colours-dark.css";
9+
@import "page-colour-scheme.css";
10+
@import "font.css";
11+
12+
@import "admonition.css";
13+
@import "button.css";
14+
@import "code-samples.css";
15+
16+
@import "wagtail-fixes/admonition-spacing.css";
17+
@import "wagtail-fixes/sticky-footer.css";
18+
@import "wagtail-fixes/table-spacing.css";
19+
@import "wagtail-fixes/top-whitespace.css";
20+
@import "wagtail-fixes/dark-theme-overrides.css";

‎_theme/css/button.css‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
/*
2+
* Styles for bootstrap buttons
3+
*/
4+
5+
.btn {
6+
/* reset the underline that wagtail adds to all `a` elements */
7+
text-decoration: none;
8+
}
9+
10+
11+
.btn-primary {
12+
background-color: var(--bh-bg-primary) !important;
13+
color: white !important;
14+
/* Fallback for older browsers */
15+
border-color: var(--bh-bg-primary) !important;
16+
/* Use color-mix to shade the border for modern browsers */
17+
border-color: color-mix(in srgb, var(--bh-bg-primary) 90%, #000) !important;
18+
}
19+
20+
.btn-primary:hover {
21+
/* These will fallback to the native theme hover colours, not pretty but it works */
22+
background-color: color-mix(in srgb, var(--bh-bg-primary) 80%, #000) !important;
23+
border-color: color-mix(in srgb, var(--bh-bg-primary) 70%, #000) !important;
24+
color: white !important;
25+
}

‎_theme/css/code-samples.css‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
/*
2+
* Customise the style of code blocks
3+
*/
4+
5+
pre, .pre {
6+
/*
7+
* The default font stack in wagtail isn't that readable on some devices.
8+
*/
9+
font-family: 'JetBrains Mono', monospace;
10+
/* Bootstrap sizes `code` inline smaller than the text surrounding it, which looks
11+
odd when we use it for things like "Behat will set up a `features` directory".
12+
*/
13+
font-size: 1rem;
14+
}
15+
16+
17+
.highlight {
18+
pre {
19+
background-color: var(--bh-code-bg);
20+
color: var(--bh-code-text);
21+
/* big code blocks can be very slightly smaller in font to fit wider line width */
22+
font-size: 0.9rem;
23+
}
24+
25+
.c, /* Comment */
26+
.cm, /* Comment.Multiline */
27+
.cp, /* Comment.Preproc */
28+
.c1, /* Comment.Single */
29+
.cs /* Comment.Special */
30+
{
31+
color: var(--bh-code-comment);
32+
}
33+
34+
.k, /* Keyword */
35+
.kc, /* Keyword.Constant */
36+
.kd, /* Keyword.Declaration */
37+
.kp, /* Keyword.Pseudo */
38+
.kr, /* Keyword.Reserved */
39+
.kt, /* Keyword.Type */
40+
.no /* Name.Constant */
41+
{
42+
color: var(--bh-code-keyword);
43+
}
44+
45+
.l, /* Literal */
46+
.il, /* Literal.Number.Integer.Long */
47+
.m, /* Literal.Number */
48+
.mf, /* Literal.Number.Float */
49+
.mh, /* Literal.Number.Hex */
50+
.mi, /* Literal.Number.Integer */
51+
.mo, /* Literal.Number.Oct */
52+
.se /* Literal.String.Escape */
53+
{
54+
color: var(--bh-code-literal);
55+
}
56+
57+
.n, /* Name */
58+
.p, /* Punctuation */
59+
.nb, /* Name.Builtin */
60+
.ni, /* Name.Entity */
61+
.nl, /* Name.Label */
62+
.nn, /* Name.Namespace */
63+
.py, /* Name.Property */
64+
.w, /* Text.Whitespace */
65+
.bp, /* Name.Builtin.Pseudo */
66+
.vc, /* Name.Variable.Class */
67+
.vg, /* Name.Variable.Global */
68+
.vi /* Name.Variable.Instance */
69+
{
70+
color: var(--bh-code-text);
71+
}
72+
73+
.nv /* Name.Variable */
74+
{
75+
color: var(--bh-code-var);
76+
}
77+
78+
79+
.o, /* Operator */
80+
.kn, /* Keyword.Namespace */
81+
.ow, /* Operator.Word */
82+
.nt /* Name.Tag */
83+
{
84+
color: var(--bh-code-operator);
85+
}
86+
87+
.ld, /* Literal.Date */
88+
.s, /* Literal.String */
89+
.sb, /* Literal.String.Backtick */
90+
.sc, /* Literal.String.Char */
91+
.sd, /* Literal.String.Doc */
92+
.s2, /* Literal.String.Double */
93+
.sh, /* Literal.String.Heredoc */
94+
.si, /* Literal.String.Interpol */
95+
.sx, /* Literal.String.Other */
96+
.sr, /* Literal.String.Regex */
97+
.s1, /* Literal.String.Single */
98+
.ss /* Literal.String.Symbol */
99+
{
100+
color: var(--bh-code-string);
101+
}
102+
103+
.na, /* Name.Attribute */
104+
.nc, /* Name.Class */
105+
.nd, /* Name.Decorator */
106+
.ne, /* Name.Exception */
107+
.nf, /* Name.Function */
108+
.nx /* Name.Other */
109+
{
110+
color: var(--bh-code-name);
111+
}
112+
}
113+
114+
/*
115+
* Customise colours for Gherkin - the wagtail/pygments defaults don't feel quite logical
116+
*/
117+
.highlight-gherkin {
118+
/* Pygment "Function Name* in gherkin is the step feature / step text etc which is more like "text" in other langs */
119+
--bh-code-name: var(--bh-code-text);
120+
/* Pygment "Variables" in gherkin is things like <placeholder> which are closer to step args */
121+
--bh-code-var: var(--bh-code-string);
122+
}

‎_theme/css/colours-brand.css‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/*
2+
* Main behat colours - based on extraction from a picture of a cucumber 😂 and then
3+
* generating complementary etc colours.
4+
*/
5+
:root {
6+
/*
7+
* Tints and shades here can be computed from brand colours using color-mix for ease
8+
* of changing / clarity about where they came from. However, the color-mix functions
9+
* need to take hardcoded colours (not variables) to allow lightningcss to compile them
10+
* out for older browsers.
11+
*/
12+
--behat-green: #506A2A;
13+
--behat-green-dk1: color-mix(in oklab, #506A2A, black 20%);
14+
--behat-green-dk2: color-mix(in oklab, #506A2A, black 40%);
15+
--behat-green-dk3: color-mix(in oklab, #506A2A, black 60%);
16+
--behat-green-dk4: color-mix(in oklab, #506A2A, black 80%);
17+
18+
/* Alternate green */
19+
--behat-green-2: #DBDFBE;
20+
--behat-green-2-dk3: color-mix(in oklab, #DBDFBE, black 60%);
21+
--behat-green-2-lt2: color-mix(in oklab, #DBDFBE, white 40%);
22+
23+
--behat-accent: #2a506a;
24+
}

‎_theme/css/colours-dark.css‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
/*
2+
* Defines variables for the dark mode theme
3+
*/
4+
body.theme-dark {
5+
/*
6+
* General page colours
7+
*/
8+
background-color: var(--behat-green-dk4) !important;
9+
color: var(--behat-green-2-lt2) !important;
10+
11+
--bh-bg-primary: var(--behat-green-dk1);
12+
--bh-link-underline: var(--behat-green-2-dk3);
13+
14+
/*
15+
* Code samples
16+
*/
17+
--bh-code-bg: var(--behat-green-dk3);
18+
19+
20+
/*
21+
* Fixes for elements that are forced to hardcoded colours by wagtail
22+
*/
23+
24+
25+
26+
27+
28+
}

‎_theme/css/colours-light.css‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Defines variables for the default (light mode) theme
3+
*/
4+
body {
5+
/*
6+
* General page colours
7+
*/
8+
--bh-bg-primary: var(--behat-green);
9+
--bh-footer-bg: var(--behat-green-dk3);
10+
11+
/*
12+
* Links
13+
*/
14+
--bh-link-color: var(--behat-green-dk1);
15+
--bh-link-underline: var(--behat-green-2);
16+
17+
--bh-link-color-current: #333;
18+
--bh-link-color-current-underline: transparent;
19+
20+
/*
21+
* Code samples
22+
*/
23+
--bh-code-bg: var(--behat-green-dk4);
24+
--bh-code-comment: #aaa;
25+
--bh-code-keyword: #66d9ef;
26+
--bh-code-literal: #ae81ff;
27+
--bh-code-text: #f8f8f2;
28+
--bh-code-var: #f8f8f2;
29+
--bh-code-operator: #f92672;
30+
--bh-code-string: #e6db74;
31+
--bh-code-name: #a6e22e;
32+
33+
34+
/*
35+
* Admonitions (tips, warnings, etc)
36+
*/
37+
--bh-admonition-title-color: #fff;
38+
--bh-adm-hint-bg: var(--behat-green);
39+
--bh-adm-tip-bg: var(--behat-accent);
40+
--bh-adm-warning-bg: #dba507;
41+
--bh-adm-danger-bg: #6a2a30;
42+
}

‎_theme/css/font.css‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/**
2+
* Use Behat (Comfortaa) font
3+
*/
4+
5+
h1,
6+
h2,
7+
h3,
8+
h4,
9+
h5 {
10+
font-family: 'Comfortaa', var(--font-family-sans-serif);
11+
}
12+
13+
header .navbar-brand {
14+
font-family: 'Comfortaa', var(--font-family-sans-serif);
15+
/*
16+
* font metrics are different to the font wagtail is using, their 1.5em is offcentre vertically with our font
17+
*/
18+
font-size: 1.25rem;
19+
}

0 commit comments

Comments
 (0)