Added contributing guide for template (#31)

Author: coretl

.github/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contribute to the template
+Contributions and issues are most welcome! All issues and pull requests are handled through [GitHub](https://github.com/DiamondLightSource/python-copier-template/issues). Also, please check for any existing issues before filing a new one. If you have a great idea but it involves big changes, please file a ticket before making a pull request! We want to make sure you don't spend your time coding something that might not fit the scope of the project.
+
+## Issue or Discussion?
+
+Github also offers [discussions](https://github.com/DiamondLightSource/python-copier-template/discussions) as a place to ask questions and share ideas. If your issue is open ended and it is not obvious when it can be "closed", please raise it as a discussion instead.
+
+## Getting changes into the template
+
+This template is a place to pull together agreed best practices from various sources. As such, it is difficult to demonstrate a change without seeing it in action in another repo. Please link to a repo that has the desired behaviour when proposing changes to the template.
+
+## Checking your changes before making a PR
+
+The template has some tests that generating from scratch and updating the [example](https://github.com/DiamondLightSource/python-copier-template-example) produce the same result, but it is difficult to that things like CI and docs are still generated correctly. You can ease this process by:
+
+- Making your changes on a branch of <https://github.com/DiamondLightSource/python-copier-template>
+- Running `copier update --vcs-ref=<branch_name>` in the repo where you would like to demonstrate the behaviour
+- Linking to that demonstration repo in the PR
+
+## Developer Information
+
+It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs.
+
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the [How-to guides](https://diamondlightsource.github.io/python-copier-template/main/how-to.html)

.github/CONTRIBUTING.rst

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

docs/explanations/decisions/0003-docs-structure.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/skeleton.rst

@@ -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.md

@@ -6,5 +6,6 @@ Practical step-by-step guides for the more experienced user.
 :maxdepth: 1
 :glob:
 
+how-to/dev-install
 how-to/*
 ```

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
+```