Proof-read documentation

[Tom-Willemsen]

Description of work

• General proof-read of the docs. Not trying to re-write major sections, but correcting sections which had become out-of-date and minor style corrections
• Improving consistency of cross-linking throughout docs to make it easier to 'drill down' to more documentation.
• Cleaning up API docs to just document our public API, not every single internal method.
• Generally making sure our API docs are rendering in a user-friendly way.

Ticket

None

Labels

Add appropriate label(s) to this PR

• 'bluesky-documentation' - Document Changes

Labels can be found of the right-hand sidebar of this PR once created

Acceptance criteria

• Pull request title is understandable for a user (e.g. scientist) reading the release notes. The PR title should be a short description of the change from a user perspective.
• Pull request has appropriate labels for automatic release-notes generation
• Outdated bits of documentation removed
• Cross-linking & formatting improved

Documentation

This entire PR is documentation.