Additional customisation / refinments of sphinx docs

[andrewphilipsmith]

Some additional ideas

• [x] Customise docs landing page
• [x] Fix Maths parsing
• [x] Include README.md in readthedocs.io pages
• [ ] Linting / tests for missing or malformed Docstrings
• [ ] Automatically show parameter/variable/member type in docs.
• [ ] Choose NumPy or Google docstring format and then enforce consistently throughout. (See napoleon extension).
• [ ] Customise templates for API docs (See this guide)
• [x] Incorporate comments for config files

[andrewphilipsmith]

Some of the items above are fixed in https://github.com/PandemiaProject/pandemia/pull/75

[James-Thompson-724]

The docstrings I've already written are in the NumPy style, so best stick with that, I think

[James-Thompson-724]

See: https://stackoverflow.com/questions/23504296/cant-make-a-bullet-list-in-restructuredtext-sphinx-readthedocs-in-the-format/23516012#23516012 for bullet list issue

[andrewphilipsmith]

For testing/linting DocStrings, try pydocstyle.

It is possible to filter by error type, which might be a helpful way to incrementally add priority docstrings, without needing to fix everything in one go.

It is also possible to configure pre-commit to work with pydocstyle. Search for "pydocstring" on the list of hooks. I would highly recommend doing this.