Render documentation to web pages

[Tom-Willemsen]

As a user & developer I would like documentation to be rendered into a nice user-facing set of pages.

We can probably do this quite easily using github actions and github pages - look at the setups in the bluesky or ophyd-async repositories for inspiration if needed (those repositories already do precisely this)

We may need to restructure our docs to fit what the automated tools expect, but this ticket is not about writing new docs, just with publishing what we already have (and restructuring if necessary)

Acceptance criteria

• [ ] Human-facing tutorials (the markdown files in doc/) are rendered into a nice navigable set of pages
  • Comparable to this
• [ ] Architectural decisions as above (but fine for these to be in a "developer" section or something like that)
  • Comparable to this
• [ ] Python-level docs (i.e. docstrings) and method signatures get used to generate docs pages
  • Comparable to this
• [ ] Pages automatically updated on new commits to main

Discussed in planning 05/09/24

28:30

[Tom-Willemsen]

Consider doing this in reusable-workflows and then just calling it here, so that the same docs CI pattern can be reused by other repos easily.