Sphinx and theme upgrades

N8-CIR-Bede / documentation

Documentation for the N8CIR Bede Tier 2 HPC faciltiy

https://bede-documentation.readthedocs.io/en/latest/

7 stars 11 forks source link

Sphinx and theme upgrades #186

Closed ptheywood closed 4 months ago

ptheywood commented 4 months ago

Updates sphinx and sphinx-book theme python dependencies to current versions.

Due to breaking changes in the theme, conf.py and custom.css changes were required. This also allowed some previous theme workarounds to be removed.

Closes #184

Todo

[x] Update sphinx and theme python requirements
[x] Bump python version in readme and ci. >= 3.9 required due to theme. 3.12 in use on CI/RTD.
[x] Customise light theme styling to match previous documentation theme
[x] Customise dark theme with N8 branding
[x] Run a11y checks on light theme
- Only pa11y reports on the few pages i've tried have been search input fields for a duplicate form from the theme which is not visible
[x] Run a11y checks on dark theme.

ptheywood commented 4 months ago

I've now completed the package upgrades, and theming adjustments due to breaking changes in the sphinx theme, including dark theming

Both themes have been checked with pa11y - there are 2 warnings about a form without a valid submission button, but it's a form which is a search form which appears when ctrl + k is pressed.

The form is included by the underlying pydata sphinx theme as part of the layout, and I'm not aware of a simple way to block out that section, so will leave those warnings for now.