Improve docs rendering

[Tom-Willemsen]

Description of work

Fix a number of issues causing docs rendering to be bad.

I still think the docs format as a whole can be improved, but these are low-hanging fruit to make our docs actually useful.

To test

Which ticket does this PR fix?

Acceptance criteria

List the acceptance criteria for the PR

---

Code Review

• Is the code of an acceptable quality?
• Are there unit tests in place? Are the unit tests small and test the a class in isolation?
• Have the changes been documented in the release notes. If so, do they describe the changes appropriately?

Functional Tests

• Do changes function as described? Add comments below that describe the tests performed.
• How do the changes handle unexpected situations, e.g. bad input?
• Has developer documentation been updated if required?