Behat · acoulton · Apr 25, 2025 · Apr 7, 2025 · Apr 8, 2025 · Apr 8, 2025
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Run build command
-        run: docker compose run --rm read-the-docs-builder
+        run: docker compose run --rm read-the-docs-builder build
 
       - name: Check build
         run: cat _build/html/guides.html

diff --git a/README.md b/README.md
@@ -39,17 +39,34 @@ built version.
 ## Building locally
 
 For more significant changes, you may want to build the full docs site locally. For this, you will need python, sphinx
-and the relevant dependencies. The easiest solution may be to use a temporary docker container. In this repository you will
-find a `Dockerfile` and a `docker-compose.yml` file that will let you do that easily
+and the relevant dependencies. 
+
+The easiest solution may be to use a temporary docker container. In this repository you will find a `Dockerfile` 
+and a `docker-compose.yml` file that will let you do that easily.
+
+You can run a one-time build:
 
 ```bash
 # Launch a docker container with the right dependencies and run the site build command
 # This will build the container if needed, using the Dockerfile
-docker compose run --rm read-the-docs-builder
+docker compose run --rm read-the-docs-builder build
 
 # The docs will be generated into _build/html
 # Check the CLI output for any errors
 ```
 
+Or you can serve the docs locally over HTTP and rebuild them automatically as you make changes:
+
+```bash
+# By default, the docs will be served on port 8000 but you can specify a custom port
+SPHINX_PORT=8129 docker compose up --remove-orphans
+
+# Browse to http://localhost:8129 (or your specified SPHINX_PORT) to see the built docs.
+# They will re-build and refresh in the browser each time you save changes.
+
+# The docs will also be generated statically into _build/html
+```
+
+
 If you encounter problems, start by looking at the logs of the latest build on Read the Docs to see the commands that
 were executed. It's possible that this README has got out of date with later changes to the build process.
diff --git a/_theme/css/admonition.css b/_theme/css/admonition.css
@@ -0,0 +1,44 @@
+/*
+ * Apply custom colour scheme to admonitions
+ * @todo could Wagtail support this as CSS variables directly?
+ */
+
+.admonition {
+    /* fallback for old browsers (they already get a border and drop shadow) */
+    background-color: transparent !important;
+    /*
+     * the panel body should be a subdued version of the title background. This can be done
+     * by mixing with transparent, which will lighten the colour in light mode, and darken
+     * it in dark.
+     */
+    background-color: color-mix(in oklab, var(--bh-admonition-bg) 15%, transparent) !important;
+
+    > .admonition-title {
+        background-color: var(--bh-admonition-bg) !important;
+        color: var(--bh-admonition-title-color) !important;
+    }
+
+    &.hint,
+    &.note {
+        --bh-admonition-bg: var(--bh-adm-hint-bg);
+    }
+
+    &.important,
+    &.seealso,
+    &.tip {
+        --bh-admonition-bg: var(--bh-adm-tip-bg);
+    }
+
+    &.caution,
+    &.warning,
+    &.attention {
+        --bh-admonition-bg: var(--bh-adm-warning-bg);
+    }
+
+    &.danger,
+    &.error {
+        --bh-admonition-bg: var(--bh-adm-danger-bg);
+    }
+
+
+}
diff --git a/_theme/css/behat-docs.css b/_theme/css/behat-docs.css
@@ -0,0 +1,20 @@
+/*
+ * Behat custom documentation CSS
+ * These CSS files are compiled together and minified with lightningcss
+ * Do not add individual styles in this file, group them together
+ */
+@import "colours-brand.css";
+@import "colours-light.css";
+@import "colours-dark.css";
+@import "page-colour-scheme.css";
+@import "font.css";
+
+@import "admonition.css";
+@import "button.css";
+@import "code-samples.css";
+
+@import "wagtail-fixes/admonition-spacing.css";
+@import "wagtail-fixes/sticky-footer.css";
+@import "wagtail-fixes/table-spacing.css";
+@import "wagtail-fixes/top-whitespace.css";
+@import "wagtail-fixes/dark-theme-overrides.css";
diff --git a/_theme/css/button.css b/_theme/css/button.css
@@ -0,0 +1,25 @@
+/*
+ * Styles for bootstrap buttons
+ */
+
+.btn {
+    /* reset the underline that wagtail adds to all `a` elements */
+    text-decoration: none;
+}
+
+
+.btn-primary {
+    background-color: var(--bh-bg-primary) !important;
+    color: white !important;
+    /* Fallback for older browsers */
+    border-color: var(--bh-bg-primary) !important;
+    /* Use color-mix to shade the border for modern browsers */
+    border-color: color-mix(in srgb, var(--bh-bg-primary) 90%, #000) !important;
+}
+
+.btn-primary:hover {
+    /* These will fallback to the native theme hover colours, not pretty but it works */
+    background-color: color-mix(in srgb, var(--bh-bg-primary) 80%, #000) !important;
+    border-color: color-mix(in srgb, var(--bh-bg-primary) 70%, #000) !important;
+    color: white !important;
+}
diff --git a/_theme/css/code-samples.css b/_theme/css/code-samples.css
@@ -0,0 +1,122 @@
+/*
+ * Customise the style of code blocks
+ */
+
+pre, .pre {
+    /*
+     * The default font stack in wagtail isn't that readable on some devices.
+     */
+    font-family: 'JetBrains Mono', monospace;
+    /* Bootstrap sizes `code` inline smaller than the text surrounding it, which looks
+       odd when we use it for things like "Behat will set up a `features` directory".
+     */
+    font-size: 1rem;
+}
+
+
+.highlight {
+    pre {
+        background-color: var(--bh-code-bg);
+        color: var(--bh-code-text);
+        /* big code blocks can be very slightly smaller in font to fit wider line width */
+        font-size: 0.9rem;
+    }
+
+    .c, /* Comment */
+    .cm, /* Comment.Multiline */
+    .cp, /* Comment.Preproc */
+    .c1, /* Comment.Single */
+    .cs /* Comment.Special */
+    {
+        color: var(--bh-code-comment);
+    }
+
+    .k, /* Keyword */
+    .kc, /* Keyword.Constant */
+    .kd, /* Keyword.Declaration */
+    .kp, /* Keyword.Pseudo */
+    .kr, /* Keyword.Reserved */
+    .kt, /* Keyword.Type */
+    .no /* Name.Constant */
+    {
+        color: var(--bh-code-keyword);
+    }
+
+    .l, /* Literal */
+    .il, /* Literal.Number.Integer.Long */
+    .m, /* Literal.Number */
+    .mf, /* Literal.Number.Float */
+    .mh, /* Literal.Number.Hex */
+    .mi, /* Literal.Number.Integer */
+    .mo, /* Literal.Number.Oct */
+    .se /* Literal.String.Escape */
+    {
+        color: var(--bh-code-literal);
+    }
+
+    .n, /* Name */
+    .p, /* Punctuation */
+    .nb, /* Name.Builtin */
+    .ni, /* Name.Entity */
+    .nl, /* Name.Label */
+    .nn, /* Name.Namespace */
+    .py, /* Name.Property */
+    .w, /* Text.Whitespace */
+    .bp, /* Name.Builtin.Pseudo */
+    .vc, /* Name.Variable.Class */
+    .vg, /* Name.Variable.Global */
+    .vi /* Name.Variable.Instance */
+    {
+        color: var(--bh-code-text);
+    }
+
+    .nv /* Name.Variable */
+    {
+        color: var(--bh-code-var);
+    }
+
+
+    .o, /* Operator */
+    .kn, /* Keyword.Namespace */
+    .ow, /* Operator.Word */
+    .nt /* Name.Tag */
+    {
+        color: var(--bh-code-operator);
+    }
+
+    .ld, /* Literal.Date */
+    .s, /* Literal.String */
+    .sb, /* Literal.String.Backtick */
+    .sc, /* Literal.String.Char */
+    .sd, /* Literal.String.Doc */
+    .s2, /* Literal.String.Double */
+    .sh, /* Literal.String.Heredoc */
+    .si, /* Literal.String.Interpol */
+    .sx, /* Literal.String.Other */
+    .sr, /* Literal.String.Regex */
+    .s1, /* Literal.String.Single */
+    .ss /* Literal.String.Symbol */
+    {
+        color: var(--bh-code-string);
+    }
+
+    .na, /* Name.Attribute */
+    .nc, /* Name.Class */
+    .nd, /* Name.Decorator */
+    .ne, /* Name.Exception */
+    .nf, /* Name.Function */
+    .nx /* Name.Other */
+    {
+        color: var(--bh-code-name);
+    }
+}
+
+/*
+ * Customise colours for Gherkin - the wagtail/pygments defaults don't feel quite logical
+ */
+.highlight-gherkin {
+    /* Pygment "Function Name* in gherkin is the step feature / step text etc which is more like "text" in other langs */
+    --bh-code-name: var(--bh-code-text);
+    /* Pygment "Variables" in gherkin is things like <placeholder> which are closer to step args */
+    --bh-code-var: var(--bh-code-string);
+}
diff --git a/_theme/css/colours-brand.css b/_theme/css/colours-brand.css
@@ -0,0 +1,24 @@
+/*
+ * Main behat colours - based on extraction from a picture of a cucumber 😂 and then
+ * generating complementary etc colours.
+ */
+:root {
+    /*
+     * Tints and shades here can be computed from brand colours using color-mix for ease
+     * of changing / clarity about where they came from. However, the color-mix functions
+     * need to take hardcoded colours (not variables) to allow lightningcss to compile them
+     * out for older browsers.
+     */
+    --behat-green: #506A2A;
+    --behat-green-dk1: color-mix(in oklab, #506A2A, black 20%);
+    --behat-green-dk2: color-mix(in oklab, #506A2A, black 40%);
+    --behat-green-dk3: color-mix(in oklab, #506A2A, black 60%);
+    --behat-green-dk4: color-mix(in oklab, #506A2A, black 80%);
+
+    /* Alternate green */
+    --behat-green-2: #DBDFBE;
+    --behat-green-2-dk3: color-mix(in oklab, #DBDFBE, black 60%);
+    --behat-green-2-lt2: color-mix(in oklab, #DBDFBE, white 40%);
+
+    --behat-accent: #2a506a;
+}
diff --git a/_theme/css/colours-dark.css b/_theme/css/colours-dark.css
@@ -0,0 +1,28 @@
+/*
+ * Defines variables for the dark mode theme
+ */
+body.theme-dark {
+    /*
+     * General page colours
+     */
+    background-color: var(--behat-green-dk4) !important;
+    color: var(--behat-green-2-lt2) !important;
+
+    --bh-bg-primary: var(--behat-green-dk1);
+    --bh-link-underline: var(--behat-green-2-dk3);
+
+    /*
+     * Code samples
+     */
+    --bh-code-bg: var(--behat-green-dk3);
+
+
+    /*
+     * Fixes for elements that are forced to hardcoded colours by wagtail
+     */
+
+
+
+
+
+}
diff --git a/_theme/css/colours-light.css b/_theme/css/colours-light.css
@@ -0,0 +1,42 @@
+/*
+ * Defines variables for the default (light mode) theme
+ */
+body {
+    /*
+     * General page colours
+     */
+    --bh-bg-primary: var(--behat-green);
+    --bh-footer-bg: var(--behat-green-dk3);
+
+    /*
+     * Links
+     */
+    --bh-link-color: var(--behat-green-dk1);
+    --bh-link-underline: var(--behat-green-2);
+
+    --bh-link-color-current: #333;
+    --bh-link-color-current-underline: transparent;
+
+    /*
+     * Code samples
+     */
+    --bh-code-bg: var(--behat-green-dk4);
+    --bh-code-comment: #aaa;
+    --bh-code-keyword: #66d9ef;
+    --bh-code-literal: #ae81ff;
+    --bh-code-text: #f8f8f2;
+    --bh-code-var: #f8f8f2;
+    --bh-code-operator: #f92672;
+    --bh-code-string: #e6db74;
+    --bh-code-name: #a6e22e;
+
+
+    /*
+     * Admonitions (tips, warnings, etc)
+     */
+    --bh-admonition-title-color: #fff;
+    --bh-adm-hint-bg: var(--behat-green);
+    --bh-adm-tip-bg: var(--behat-accent);
+    --bh-adm-warning-bg: #dba507;
+    --bh-adm-danger-bg: #6a2a30;
+}
diff --git a/_theme/css/font.css b/_theme/css/font.css
@@ -0,0 +1,19 @@
+/**
+ * Use Behat (Comfortaa) font
+ */
+
+h1,
+h2,
+h3,
+h4,
+h5 {
+    font-family: 'Comfortaa', var(--font-family-sans-serif);
+}
+
+header .navbar-brand {
+    font-family: 'Comfortaa', var(--font-family-sans-serif);
+    /*
+     * font metrics are different to the font wagtail is using, their 1.5em is offcentre vertically with our font
+     */
+    font-size: 1.25rem;
+}