Switch to (branded) alternate sphinx theme

[ptheywood]

While working on splitting the source / using toctree more heavily, issues with the sphinx-bootstrap theme have been cropping up that are hard to workaround, or are not trivial to resolve.

This includes:

• The width of the sidebar being limited, resulting in small text and empty margin
• Sidebar current entry highlighting for in-page content is not implemented (requires css + js)
• Hard to read <pre> content
• Hard to read content in info and warning blocks, which are difficult to restyle without changing the theme (Bold colours are good for headers, but make reading longer text more difficult)
• Navbar hiding content (#80)

Many of these would be resolved by switching to the sphinx-rtd-theme, with rebranding of colours.

This is essentially duplicating previous work, but it should be less effort than manually modifying the sphinx-bootstrap-theme to address the issues highlighted above.

As other potential alternative themes, furo and pydata-sphinx-them are potential alternatives

If any big theme changes are made, it would also be worthwhile ensuring accessibility guideleines are met (#42)

[ptheywood]

Some testing of other sphinx themes without significant branding for reference, to see if they resolve the issues above. Further branding would be possible if the switch is deemed worthwhile.

sphinx-rtd-theme

furo

Furo has a user-toggleable dark and light theme, It should be possible to configure the default or disable this if it complicates and custom css.

Light

Dark

pydata

[markdturner]

Furo looks the best if it can be made to include in-page navigation.

[ptheywood]

Furo's developer / maintainer has marked issues for combining the site navigation and page navigation into a single sidebar as wontfix, as it is intended to be separate.

https://github.com/pradyunsg/furo/issues/79

I'm not convinced the split site and page toc is the better option, especially when both fold/collapse independently so the second toc may not be found by users.

We could probably override furo's toc implementation to include the page navigation, but this might be a decent amount of effort, so I'll likely fallback to rtd-theme unfortunately.

sphinx-book-theme is another modern theme, but again this implements a right-hand content sidebar, but does not collapse it as readily as furo.

[ptheywood]

Material theme

A few other HPC centres (Archer2, baskerville) use mkdocs based documentation with the Material theme. There is a sphinx port of this theme, which splits the navigation and page content like Furo, but does not fold the in-page nav as aggressively.

However it does fold the site navigation quite early, and the mobile navigation lackas any indication of depth:

It is not clearly under development/active maintenance however.

Sphinx-book-theme

The sphinx book theme mentioned in the previous comment seems like a good option for a non-RTD theme which splits the navigation and in-page tocs.

My only real complaint so far is the in-page highlighting of the current element does not behave well with short sections, as it skips some headings depending on content length.

I.e. the Installing Conda Packages section is never actively highlighted

I'd also like the topbar to include the n8cir logo when the side-nav is folded away, but i've not looked into this yet.

I'll spend a short amount of time customising/branding sphinx-rtd-theme and sphinx-book-theme to see how they look with branding, then potentially reach out for feedback on which option is prefferred unless a clear winner arises.

Additionally, the annoucnement theme option of sphinx-book-theme could be very useful for important status updates, such as the Rhel8 migration.

https://sphinx-book-theme.readthedocs.io/en/latest/customize/announcements.html

[ptheywood]

Simple customisation of the sphinx-book-theme, pushed to theme-test-book.

If selected over RTD, there's still a bit more work to be done

• Run it through accessibililty toools
  • Likely requires the orange changing
• The page footer states By N8 CIR which is redundent, this might need the footer theme template overriding.
  • It would also be good to add the Made with sphinx, using the sphinx-book-theme text for attribution (not required but a good thing to do).
• The link in the annoucement text is not an actual destination yet, and can't use :ref: in conf.py
• Codeblock styling
• Testing with RTD extensions (version selector, ethical ads)

So far switching to this has greatly reduced the amount of custom CSS required to workaround issues, and fixes the major problems with the boostrap theme highlighted at the start of this issue.

[ptheywood]

After some (minor) customisation / branding of the sphinx-rtd-theme, pushed to theme-test-rtd.

If selected over the book theme, it would still benefit from:

• Running through accessibility tools
• pre/code/syntax highlighting theme changes
• Potentially custom annoucnement area at the top of each page, just for the RHEL 8 migration or simple per-page additions of key informaiton (i.e. if there are major outages in the future).

[ptheywood]

I've set up temporary hosted demos of the RTD and book themes via ghpages + repo forks for demos withotu local builds being required:

• sphinx-book-theme: https://ptheywood.uk/bede-docs-demo-book/
• sphinx-rtd-theme: https://ptheywood.uk/bede-docs-demo-rtd/
• Current: https://bede-documentation.readthedocs.io/