Updated more docs

Author: coretl

docs/explanations/decisions/0003-docs-structure.rst

@@ -1,4 +1,4 @@
-.. _documentation structure:
+.. _documentation-structure:
 
 3. Standard documentation structure
 ===================================

docs/explanations/skeleton.rst

@@ -0,0 +1,38 @@
+# Template Project Structure
+
+The template has the following folders at the root level.
+
+## src
+
+This folder contains the source code for the project. Typically this contains a single folder with the package name for the project and the folder contains python modules files.
+
+See [](src) for details.
+
+## tests
+
+This folder holds all of the tests that will be run by pytest, both locally and in CI.
+
+See [](using-pytest)
+
+## docs
+
+This folder contains the source for sphinx documentation.
+
+See [](documentation-structure) for details.
+
+## .github
+
+Configuration for the Continuous Integration Workflow on github
+
+## VSCode specific folders
+
+### .devcontainer
+
+Configuration for running the developer container for this project in VSCode.
+
+### .vscode
+
+VSCode settings for this project:
+
+- enable static analysis in the editor
+- enables python debugging.

docs/explanations/structure.md

@@ -0,0 +1,9 @@
+# Why Use a Copier Template?
+
+Many projects start from some kind of template. These define some basic structure, customized with project specific variables, that developers can add their code into. One example of this is [cookiecutter](https://cookiecutter.readthedocs.io).
+
+The problem with this approach is that it is difficult to apply changes to the template into projects that have been cut from it. Individual changes have to be copy/pasted into the code, leading to partially applied fixes and missed updates.
+
+A previous attempt, [python3-pip-skeleton](https://github.com/DiamondLightSource/python3-pip-skeleton), took a different approach, being a repo that can be forked and updates merged into projects tracking it. This was initially encouraging, but led to downstream confusion on who had actually contributed to the repository, as well as messy merges when text that contained the project name (like documentation) was changed upstream.
+
+This template now makes use of [copier](https://copier.readthedocs.io/) which gives the best of both worlds, a templating engine to expand the template, then an update mechanism to apply diffs of the updated template to the project.

docs/explanations/structure.rst

@@ -0,0 +1,39 @@
+# Build the docs using sphinx
+
+You can build the [sphinx](https://www.sphinx-doc.org) based docs from the project directory by running:
+
+```
+$ tox -e docs
+```
+
+This will build the static docs on the `docs` directory, which includes API docs that pull in docstrings from the code.
+
+:::{seealso}
+[](documentation_standards)
+:::
+
+The docs will be built into the `build/html` directory, and can be opened locally with a web browse:
+
+```
+$ firefox build/html/index.html
+```
+
+## Autobuild
+
+You can also run an autobuild process, which will watch your `docs` directory for changes and rebuild whenever it sees changes, reloading any browsers watching the pages:
+
+```
+$ tox -e docs autobuild
+```
+
+You can view the pages at localhost:
+
+```
+$ firefox http://localhost:8000
+```
+
+If you are making changes to source code too, you can tell it to watch changes in this directory too:
+
+```
+$ tox -e docs autobuild -- --watch src
+```

docs/explanations/why-use-skeleton.rst

@@ -0,0 +1,46 @@
+# Setup Developer Environment
+
+These instructions will take you through the minimal steps required to get a dev environment setup, so you can run the tests locally.
+
+## Clone the repository
+
+First clone the repository locally using [Git](https://git-scm.com/downloads). There is a link on the GitHub interface to allow you to do this. SSH is recommended if you have setup a key. Enter the directory that it is cloned into to continue.
+
+## Install dependencies
+
+You can choose to either develop on the host machine using a `venv` (which requires python 3.8 or later) or to run in a container under [VSCode](https://code.visualstudio.com/)
+
+<!-- https://sphinx-design.readthedocs.io/en/latest/tabs.html# -->
+::::{tab-set}
+
+:::{tab-item} Local virtualenv
+```
+python3 -m venv venv
+source venv/bin/activate
+pip install -c requirements/constraints.txt -e .[dev]
+```
+:::
+
+:::{tab-item} VSCode devcontainer
+```
+code .
+# Click on 'Reopen in Container' when prompted
+# Open a new terminal
+:::
+
+::::
+
+## Build and test
+
+Now you have a development environment you can run the tests in a terminal:
+
+```
+tox -p
+```
+
+This will run in parallel the following checks:
+
+- [](./build-docs)
+- [](./run-tests)
+- [](./static-analysis)
+- [](./lint)