Mkdocs development

.github/workflows/build-documentation.yml

@@ -0,0 +1,34 @@
+name: "Build and Deploy documentation to GH Pages"
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build the MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.github/workflows/govcookiecutter-build.yml

@@ -32,10 +32,10 @@ jobs:
       - name: Create documentation
         run: |
           if [[ "$RUNNER_OS" == "Linux" || "$RUNNER_OS" == "macOS" ]]; then
-            sphinx-build -b html ./docs ./docs/_build
+            mkdocs build -c -s
           elif [ "$RUNNER_OS" == "Windows" ]; then
             # TODO: Investigate why Sphinx build raises a warning on Windows but not Unix
-            sphinx-build -b html ./docs ./docs/_build -Q
+            mkdocs build -c -s
           else
             echo "$RUNNER_OS not supported"
             exit 1

CHANGELOG.md

@@ -8,12 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased] -
 
 ### Added
+- Use of Mkdocs and material for mkdocs to create HTML documentation
 
 ### Fixed
 
 ### Changed
+- Structure of Docs folder, combined and removed files to simplify folder structure
+- Reviewed accessibility statement
 
 ### Removed
+- Sphinx documentation
 
 ## [1.0.0] - 18th July 2025
 

docs/_static/mkdocs_custom.css

@@ -0,0 +1,46 @@
+[data-md-color-scheme="default"]  {
+  --md-primary-fg-color:        #003C57;
+  --md-primary-fg-color--light: #003C57;
+  --md-primary-fg-color--dark:  #003C57;
+  --md-accent-fg-color:        #F46A25;
+  --md-accent-fg-color--light: #F46A25;
+  --md-accent-fg-color--dark:  #F46A25;
+    /* Set hyperlink color */
+  --md-typeset-a-color: #28A197;
+  --md-typeset-a-color--hover: #003C57;
+
+  --title-font-color: #003C57;
+  --md-footer-bg-color: #095b81;
+  --md-footer-bg-color--dark: #003C57;
+
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color:        #003C57;
+  --md-primary-fg-color--light: #003C57;
+  --md-primary-fg-color--dark:  #003C57;
+  --md-accent-fg-color:        #F46A25;
+  --md-accent-fg-color--light: #f57c3f;
+  --md-accent-fg-color--dark:  #8e3f18;
+  /* Set hyperlink color */
+  --md-typeset-a-color: #28A197;
+  --md-typeset-a-color--hover: #003C57;
+  --md-code-bg-color: #3D3D3D;
+  --md-footer-bg-color: #003C57;
+  --title-font-color: #F46A25;
+  --md-footer-bg-color: #0b2b3a;
+  --md-footer-bg-color--dark: #003C57;
+
+  /* --md-default-bg-color: #3D3D3D; */
+  /* --md-typeset-color: #ffffff; */
+  /* --md-default-bg-color: #3D3D3D; */
+}
+
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-typeset h5,
+.md-typeset h6 {
+    color: var(--title-font-color);
+}

docs/accessibility.md

@@ -77,8 +77,7 @@ The content listed below is non-accessible for the following reasons.
 #### Disproportionate burden
 
 [The use of layout tables are due to the use of the
-`sphinx.ext.autosummary`][sphinx-autosummary], and [`sphinx.ext.autodoc`
-extensions][sphinx-autodoc]. This is a third-party, open source code base, and so is
+`mkdocstrings`][mkdocstrings]. This is a third-party, open source code base, and so is
 beyond the scope of this project to fix, although we will apply updates as this
 codebase develops.
 
@@ -98,20 +97,19 @@ They tested all pages on this site.
 
 ## What we're doing to improve accessibility
 
-We plan to fix the accessibility issues in the content by the end of December 2021.
+We plan to fix the accessibility issues in the content by the end of December 2025.
 
 ## Preparation of this accessibility statement
 
-This statement was prepared on 30 June 2021. It was last reviewed on 20 July 2021.
+This statement was prepared on 30 June 2021. It was last reviewed on 30 July 2025.
 
 [abilitynet]: https://abilitynet.org.uk/
 [accessibility-legislation]: https://www.legislation.gov.uk/uksi/2018/952/regulation/4/made
 [eass]: https://www.equalityadvisoryservice.com/
 [email]: mailto:gsshelp@statistics.gov.uk
 [github-issues]: https://github.com/best-practice-and-impact/govcookiecutter-lite/issues/new
 [github-pages]: https://best-practice-and-impact.github.io/govcookiecutter-lite
-[sphinx-autodoc]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
-[sphinx-autosummary]: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
+[mkdocstrings]: https://mkdocstrings.github.io/
 [wave]: https://wave.webaim.org/
 [wcag]: https://www.w3.org/TR/WCAG21/
 [wcag-2.1-1.3.1]: https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html

CONTRIBUTING.md → docs/contributing/CONTRIBUTING.md

@@ -1,9 +1,9 @@
 # Contributing
 
 We love contributions! We've compiled this documentation to help you understand our
-contributing guidelines. Please also read our [`CODE_OF_CONDUCT.md`][code-of-conduct].
+contributing guidelines. Please also read our [code of conduct](./CODE_OF_CONDUCT.md).
 
-If you still have questions, please contact us at ASAP@ons.gov.uk and we'd be happy to help!
+If you still have questions, please contact us at [ASAP@ons.gov.uk][asap-email] and we'd be happy to help!
 
 
 ## Getting started
@@ -50,7 +50,7 @@ Raise an issue using the bug report template - please check the [issues][issues]
 
 ### Want to see a new feature?
 
-We'd be delighted to consider it! Please raise an issue using the feature request template after checking the [issues][issues] in case you can add to an ongoing discussion.
+We'd be delighted to consider it! Please [raise an issue][new-issue] using the feature request template after checking the [issues][issues] in case you can add to an ongoing discussion.
 
 ### Markdown
 
@@ -100,21 +100,24 @@ The HTML report can be accessed at `htmlcov/index.html`.
 
 Documentation is stored in the `docs` folder unless it's more
 appropriate to store it elsewhere, like this contributing guidance. We
-write our documentation in [MyST Markdown][myst] for use in [Sphinx][sphinx], to make
-a searchable wesite. Public sector websites must be accessible by law, and GOV.UK has
+write our documentation in [MyST Markdown][myst] for use in [mkdocs][mkdocs], to make
+a searchable website. Public sector websites must be accessible by law, and GOV.UK has
 further information on these [requirements][gov-uk-accessibility].
 
 To create the website locally, run the following command in your terminal
 at the top-level of this project:
 
 ```shell
-make docs
+mkdocs build
 ```
 
-This should create an HTML version of your documentation accessible from
-`docs/_build/index.html`.
+or make an interactive version to view live changes run:
 
-[code-of-conduct]: https://github.com/best-practice-and-impact/govcookiecutter/blob/main/CODE_OF_CONDUCT.md
+```shell
+mkdocs serve
+```
+
+[asap-email]: mailto:ASAP@ons.gov.uk
 [coverage]: https://coverage.readthedocs.io/
 [detect-secrets-repo]: https://github.com/Yelp/detect-secrets/tree/master
 [duck-book-version-control]: https://best-practice-and-impact.github.io/qa-of-code-guidance/version_control.html
@@ -123,9 +126,10 @@ This should create an HTML version of your documentation accessible from
 [gitignore-io]: https://www.toptal.com/developers/gitignore
 [gov-uk-accessibility]: https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps
 [gov-uk]: https://www.gov.uk/
-[issues]: https://github.com/best-practice-and-impact/govcookiecutter/issues/new
+[issues]: https://github.com/best-practice-and-impact/govcookiecutter-lite/issues
+[new-issue]: https://github.com/best-practice-and-impact/govcookiecutter-lite/issues/new
 [myst]: https://myst-parser.readthedocs.io/
 [nbstripout-repo]: https://github.com/kynan/nbstripout
 [pre-commit]: https://pre-commit.com
 [pytest]: https://docs.pytest.org/
-[sphinx]: https://www.sphinx-doc.org/en/master/index.html
+[mkdocs]: https://www.mkdocs.org/