Update documentation, update vale

[Andy-Grigg]

Closes #389
Closes #256

Restructure the documentation to be more like grantami-jobqueue, which involves re-using some elements of the README in the getting started section.

Also update the vale config to use the new version.

@PipKat I haven't changed a whole lot here, but it's been a while since this documentation was written. Also, I believe the last major release was reviewed by the MatBU docs team, but not by you.

This PR paves the way for us to make the API documentation terser in the future if we should decide do, by moving the prose to the User Guide section.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.32%. Comparing base (54016da) to head (01216ce).
Report is 9 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #483   +/-   ##
=======================================
  Coverage   97.32%   97.32%           
=======================================
  Files          18       18           
  Lines        2434     2434           
=======================================
  Hits         2369     2369           
  Misses         65       65           

Flag	Coverage Δ
integration	82.49% <100.00%> (ø)
unittests	96.87% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[ludovicsteinbach]

Looks good.

[PipKat]

@Andy-Grigg I found places where we weren't following the Google style guidelines, especially in the examples. Sorry that my commit ended up with changes to so many files. As always, reach out with any questions.

[Andy-Grigg]

@Andy-Grigg I found places where we weren't following the Google style guidelines, especially in the examples. Sorry that my commit ended up with changes to so many files. As always, reach out with any questions.

It's all good, thank you for the review!