🚚 Move docs instructions to CONTRIBUTING.md

CONTRIBUTING.md

@@ -34,7 +34,7 @@ The most pertinent features of the DevOps methodology for this project are:
 - **automation**: maximal automation is the primary goal
 - **quality**: full integration testing each time features are added
 
-### Project workflow
+## Project workflow
 
 Although we are not following an Agile workflow, we still think that the following features are important:
 
@@ -70,11 +70,19 @@ This means that:
 
 - checking out the `latest` branch, will give you the latest tagged release
 - the `develop` branch, which is the default branch of the repository, contains the latest cutting-edge code that has not yet made it into a release
-- releases are made by branching from `develop` into a branch called `release-<version name>`
-    - deployment is tested from this release and any necessary integration changes are made on this branch
-    - the branch is then merged into `latest` (which is tagged) as the next release **and** into `develop` so that any fixes are included there
 - we prefer to use [merge commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github) in order to avoid rewriting the git history
 
+### Issues as conversations
+
+If you have an idea for a piece of work to complete, please **open an issue**.
+
+The name `issue` comes from a concept of catching errors (bugs :bug:) in software, but for this project they are simply our **tasks**.
+If an issue is growing to encompass more than one task, consider breaking it into multiple issues.
+
+You can think of the issues as **conversations** about a particular topic.
+`GitHub`'s tagline is **social coding** and the issues are inspired by social media conversations.
+Alternatively (and this is encouraged) you can use the issue to keep track of where you're up to with the task and add information about next steps and barriers.
+
 ### Discussions vs Issues
 
 **Discussions** are the best place for informal talk about the project
@@ -106,16 +114,7 @@ Each issue should be assigned to an appropriate [milestone](https://github.com/a
 If you have been assigned an issue, please be ready to explain in the [project meeting](#project-meetings) what your progress has been.
 In a perfect world you'll have completed the task, documented everything you need to and we'll be able to **close** the issue (to mark it as complete).
 
-### Issues as conversations
-
-If you have an idea for a piece of work to complete, please **open an issue**.
-
-The name `issue` comes from a concept of catching errors (bugs :bug:) in software, but for this project they are simply our **tasks**.
-If an issue is growing to encompass more than one task, consider breaking it into multiple issues.
-
-You can think of the issues as **conversations** about a particular topic.
-`GitHub`'s tagline is **social coding** and the issues are inspired by social media conversations.
-Alternatively (and this is encouraged) you can use the issue to keep track of where you're up to with the task and add information about next steps and barriers.
+## Contributing your changes
 
 ### Making a change with a pull request
 
@@ -128,12 +127,44 @@ To contribute to the codebase you'll need to:
 ### Making a change to the documentation
 
 The docs, including for older releases, are available [here](https://data-safe-haven.readthedocs.io).
-
 You should follow the same instructions as above to [make a change with a pull request](#making-a-change-with-a-pull-request) when editing the documentation.
 
-To preview your changes, you can build the docs locally. See [docs/README.md](docs/README.md).
+The documentation is built from Markdown files using [Sphinx](https://www.sphinx-doc.org/) and [MyST parser](https://myst-parser.readthedocs.io/).
+To preview your changes, you can build the docs locally with `hatch`:
+
+```console
+> hatch run docs:build
+```
+
+- The generated documents will be placed under `build/html/`.
+- To view the documents open `build/html/index.html` in your browser, for example:
+
+```console
+> firefox build/html/index.html
+```
+
+## Preparing a new release
+
+Releases are made by branching from `develop` into a branch called `release-<version name>`
+
+- deployment is tested from this release and any necessary integration changes are made on this branch
+- the branch is then merged into `latest` (which is tagged) as the next release **and** into `develop` so that any fixes are included there
+
+The release can then be published to PyPI:
+
+- Build the tarball and wheel
+
+```console
+> hatch run build
+```
+
+- Upload to PyPI, providing your API token at the prompt
+
+```console
+$ hatch run publish --user __token__
+```
 
-### Who's involved in the project
+## Who's involved in the project
 
 Take a look at the full list of contributors on our [README](README.md).
 
@@ -149,7 +180,7 @@ To add new contributor to the README table, see the [all-contributors CLI docume
 
 You can get in touch with the development team at [email protected].
 
-## Thank you!
+**Thank you!**
 
 You're awesome! :wave::smiley: