Migrate documentation generation to mkdocs

[timcnicholls]

This PR migrates the documentation generation from sphinx to mkdocs. The documentation contents remain a work-in-progress but the primary structure is present, with a complete "getting started" guide. API reference auto-generation is also configured and built.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (d4d29bd) to head (15b2329).
⚠️ Report is 1 commits behind head on dev_2.0.

Additional details and impacted files

@@            Coverage Diff            @@
##           dev_2.0       #83   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           30        30           
  Lines         1674      1674           
=========================================
  Hits          1674      1674           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[timcnicholls]

Notify jobs are failing as the Slack org was deleted. These will be removed by #84

[JamesOHeaDLS]

The rest of the changes look good and I have been able to run mkdocs serve locally.

What are your thoughts on the breaking changes of mkdocs 2.0, and the ProperDocs fork? I followed the link in a warning that came up when running mkdocs serve and have discovered that mkdocs seems to be a dead project with a lot of animosity between the maintainers - see https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

[timcnicholls]

The rest of the changes look good and I have been able to run mkdocs serve locally.

What are your thoughts on the breaking changes of mkdocs 2.0, and the ProperDocs fork? I followed the link in a warning that came up when running mkdocs serve and have discovered that mkdocs seems to be a dead project with a lot of animosity between the maintainers - see https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

My feeling was that the current version is still sufficiently usable (and, IMO, much easier to configure and use than e.g. sphinx) that it is worth the transition for now, especially if it helps get documetnation written 😉 The mkdocs-material team are plugging their own tool Zeniscal, which is currently in alpha but will likely provide a usable migration path once it matures.

I wasn't aware of ProperDocs, but that might be a good intermediate solution if it plays nicely with mkdocs-material. I'll take a look.

[ajgdls]

@timcnicholls totally minor point, the transparent background logo looked slightly lost in the blue background of my locally served docs, if you have one with a white(?) bg and border might be worth using that.
Completely minor observation!

[timcnicholls]

@timcnicholls totally minor point, the transparent background logo looked slightly lost in the blue background of my locally served docs, if you have one with a white(?) bg and border might be worth using that. Completely minor observation!

@ajgdls I think it's the size rather than the background that makes it look lost? If I change to a white background it still doesn't look great I think:

It is possible to increase the size with a bit of CSS magic:

which I think looks cleaner even without the white background. What do you you think?

[ajgdls]

@timcnicholls totally minor point, the transparent background logo looked slightly lost in the blue background of my locally served docs, if you have one with a white(?) bg and border might be worth using that. Completely minor observation!

@ajgdls I think it's the size rather than the background that makes it look lost? If I change to a white background it still doesn't look great I think:

It is possible to increase the size with a bit of CSS magic: which I think looks cleaner even without the white background. What do you you think?

Ah yes sure that larger version does look better 👍

[timcnicholls]

Latest commits migrate to using properdocs and mkdocs-materialx and fix icon size in top bar

[JamesOHeaDLS]

Cool! Looks good and runs up nicely under properdocs