docs: Reworks documentation to use mkdocs

[ns-rse]

Closes #1075

On the back of positive feedback on the AFMReader website in todays
Code Clean I got stuck in refactoring the code to use mkdocs.

Not quite there yet as the following need addressing.

• versioning is configured but not
  used. This may be my misunderstanding of how the extension is meant to work as I thought it would make new sites for
  each version. Reading the mike documentation this may not be the case and it may
  require a one-off task of sitting down and going through building documentation on the gh-pages branch locally for
  each version we wish to provision documentation for.
• syntax highlighting is again configured but
  not working/used when the site is rendered. Need to work out why.
• expanding menus - these work when using the material theme without any action but don't when using the terminal
  theme which the team liked.

To test this out locally you can...

git switch main
git pull
git checkout ns-rse/1075-mkdocs
pip install -e .[docs]
mkdocs serve

...and got to the URL output in the terminal.

---

• Documentation has been updated and builds. Remember to update as required...

[ns-rse]

I've explicitly ignored the OT string in the Mermaid diagram.

The other pre-commit error rises from the check-yaml hook not being able to recognise a constructor for the entry required in mkdocs.yaml to ring fence the Mermaid diagram (required to get it to render correctly).

I can't see any method of ignoring this individual line as the pre-commit set of hooks operate on a per-file basis. We could add exclude: [ "mkdocs.yml" ] (or similar) but then lose the benefit of having the rest of the syntax checked in this file so I'd rather just accept that pre-commit will always fail on that one line as in theory it should only be run against that file when it is modified (I'll keep an eye on this and if its repeatedly failing will exclude it).

[ns-rse]

Reading through the documentation for mike, the Mkdocs extension that builds and
manages multiple versions of documentation it looks like we will have to use...

mike depoly [version]

...to build documentation for older versions/releases. It is a little unclear but it is stated that it will
update versions of documentation on the gh-pages branch and
suggests that existing versions should be deleted first.

Currently though we don't have any versions released with mkdocs on the gh-pages branch since we have been using
sphinx-multiversion to build and deploy.

I think a useful strategy would therefore be to merge this pull request which will trigger building and deployment of
the documentation using mkdocs. We can then undertake manually building the documentation for the versions we
currently have available which are...

• v2.0.0
• v2.1.0
• v2.1.1
• v2.1.2
• v2.2.0
• v2.2.1
• v2.2.post0
• v2.3.1
• main

...and have these manually uploaded. Probably not quite as straight-forward as it sounds but would be useful to get
these updated.

[ns-rse]

I've been having a play around with mike this morning to try and work out how to get documentation for older versions deployed via GitHub pages.

So that I don't mess anything up I forked to ns-rse/TopoStats and have been
playing with that.

It's a bit of a faff to sort out the versioned documentation as it requires making...

• git checkout v#.#.# - Checkout the tagged commit.
• git switch -c mkdocs-v#.#.# - Make a new branch.
• Add the following..
  • mkdocs.yaml - edit to reflect the top level structure in existing docs/index.rst, should include the pages and
    the API.
  • docs/index.md - A markdown version of docs/index.rst that just lists the pages (not the API).
• mike serve - build the documentation for this version and serve locally
• git add mkdocs.yaml docs/index.md site/ - add commited changes
• mike deploy -m "docs: building docs for v#.#.# with mike" --push v#.#.# - should push to the gh-pages branch but
  doesn't appear to work, I get a warning: nothing changed in commit / To create a commit anyway, retry with --allow-empty. Doing so appears to work ok though.

You can now go to https://blog.nshephard.dev/TopoStats/latest/ and pick
between versions (although the v2.2.0 / v2.2.1 are wrong as I built them off of v2.3.1 by mistake, but you can
see the differences between v2.0.0. I think I may need to modify a setting in mkdocs.yaml although the
extra.version.default is meant to be latest so not sure why going to
https://blog.nshephard.dev/TopoStats/ doesn't redirect to latest/