Skip to content

Documentation improvements

Richard Bowman requested to merge fix-readthedocs into master

This branch sorts out a couple of things with the docs:

  • We now have some basic "user manual" documentation for the webb application.
  • Readthedocs now builds again.
  • We link to externally hosted API docs, for now using redoc's example page but a URL that points to our build server to retrieve the OpenAPI description.

Embedding the API documentation in the Sphinx docs was not helping, and neither of the two plugins I used to render the OpenAPI description did as good a job as a statically hosted redoc or swagger-ui instance. I've therefore removed the openapi description from the documentation, but we will prioritise having a self-hosted instance of the API docs.

Things to do:

  • Remove API docs and associated extensions from Sphinx config
  • Update CI so that openapi YAML is deployed to the build server
  • Add user manual to readthedocs
  • Fix the link that currently points to a temp directory on the build server, to point to a release.
Edited by Richard Bowman

Merge request reports