[DOC] Misc small fixes for code documentation & docsite

[TomDonoghue]

This PR includes small tweaks for code, documentation, and the docsite:

• a sweep through of in-code documentation
  • in particular, add docstrings to property attributes, so these get rendered on the docsite
• a sweep through of the documentation site
• a sweep through of code linting
  • biggest updates are to remove 'dangerous' defaults of empty collection items, and replace to have optional parameters default to None, and then deal with the None values

@ryanhammonds : this started as some small follow ups from your PR that I didn't want to start making nitpicky comments about. In terms of review, it would be great if you can throw a quick check through the file diffs, keeping an eye out for any typos, weirdnesses or quirks, and also just check you can pull this branch and build the docsite and nothing goes haywire, but otherwise this doesn't need an extensive review (also no rush on it).

[ryanhammonds]

👍