Adding Sphinx docs to template

[matt-graham]

Would resolve #16

Adds Sphinx documentation to template using sphinx-autodoc2 to generate API documentation and using MyST parser to allow use of Markdown in docstrings (and documentation pages). Also sets up a few other extensions - sphinx.ext.intersphinx for automatic links to other documentation with by default only the Python standard library index included, and sphinx.ext.viewcode to add links to source code. This is set up to use the PyData Sphinx theme which @samcunliffe recommeded on another project. A tox environment docs is added to simplify building documentation.

This was mainly intended as a demonstration that it's possible to get Sphinx set up in a way which will easy for users to use and doesn't require much boilerplate for reference in discussion in #16. It's not clear yet if we would want to go with Sphinx rather than Mkdocs.

I also haven't yet added any default workflows to the template for building docs - ideally we'd want to make it easy to automatically deploy to GitHub pages but this would require some manual intervention from user to specify where GitHub pages site should be generated from. We could as an intermediate step just have a workflow for testing docs build, with a commented out step for subsequently doing deployment on pushes to main with instructions to user to do necessary configuration before uncommenting.

EDIT: Screenshot of what generated documentation website looks like

To dos

• Add workflow for testing building documentation on pull-requests and pushes to main (for example https://github.com/UCL/neso-calibration/blob/main/.github/workflows/docs.yml)
• Add instructions of how to set up automatic deployment to GitHub pages in main README or as option in cookiecutter similar to git init
• Add instructions for how to build documentation to template README.md
• Decide whether to include README.md content in docs

[samcunliffe]

Decide whether to include README.md content in docs

I do quite like this. Sphinx vs MkDocs aside. It's DRY.

[matt-graham]

Closing in favour of #319 as consensus decision in #16 is to add MkDocs instead to template.