Merge pull request #33 from ukgovdatascience/revise-documentation

Revise documentation

.github/pull_request_template.md

@@ -1,8 +1,8 @@
 # Summary
 
-Add your summary here - keep it brief, to the point, and in plain English. For further
-information about pull requests, check out the
-[GDS Way](https://gds-way.cloudapps.digital/standards/pull-requests.html).
+Add your summary here - keep it brief, to the point, and in plain English. [For further
+information about pull requests, check out the GDS
+Way](https://gds-way.cloudapps.digital/standards/pull-requests.html).
 
 # Checklists
 
@@ -18,12 +18,12 @@ the reviewers' discretion.
 
 This pull/merge request meets the following requirements:
 
-- [ ] Code runs
-- [ ] Developments are **secure** and [**ethical**][data-ethics-framework]
-- [ ] You have made proportionate checks that the code works correctly
-- [ ] You have tested the build of the template
-- [ ] Test suite passes
-- [ ] [Minimum usable documentation][agilemodeling] written in the `docs` folder
+- [ ] code runs
+- [ ] [developments are ethical][data-ethics-framework] and secure
+- [ ] you have made proportionate checks that the code works correctly
+- [ ] you have tested the build of the template
+- [ ] test suite passes
+- [ ] [minimum usable documentation][agilemodeling] written in the `docs` folder
 
 Comments have been added below around the incomplete checks.
 

.github/workflows/govcookiecutter-build.yml

@@ -43,6 +43,7 @@ jobs:
             echo "$RUNNER_OS not supported"
             exit 1
           fi;
+          sphinx-build -b linkcheck ./docs ./docs/_linkcheck
         shell: bash
       - name: Execute tests, and create coverage report
         run: |

.github/workflows/govcookiecutter-deploy-documentation.yml

@@ -0,0 +1,25 @@
+name: govcookiecutter deploy documentation
+
+on:
+  release:
+    types: [ released ]
+
+jobs:
+  deploy-documentation:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Install requirements, and build documentation
+        run: make docs
+      - name: Publish to GitHub Pages
+        if: startsWith(github.ref, 'refs/tags')
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: docs/_build

.github/workflows/govcookiecutter-template-build.yml

@@ -65,6 +65,7 @@ jobs:
             echo "$RUNNER_OS not supported"
             exit 1
           fi;
+          sphinx-build -b linkcheck ./docs ./docs/_linkcheck
         shell: bash
       - name: Run pre-commit hooks
         run: |

.gitignore

@@ -862,3 +862,6 @@ docs/reference/api/*
 # Ignore `example` folder, but not its `README.md`
 example/*
 !example/README.md
+
+# Ignore Sphinx documentation link checking folder
+docs/_linkcheck/

CODE_OF_CONDUCT.md

@@ -1,14 +1,13 @@
 # Code of conduct for `govcookiecutter`
 
 Contributors to this repository hosted by `ukgovdatascience` are expected to follow the
-Contributor Covenant Code of Conduct, and those working within Her Majesty's Government
-are also expected to follow the Civil Service Code.
+Contributor Covenant Code of Conduct. Contributors working within Her Majesty's
+Government are also expected to follow the Civil Service Code.
 
 ## Civil Service Code
 
-Contributors working within Her Majesty's Government must review the
-[Civil Service Code][civil-service-code], and are expected to follow it in their
-contributions.
+Contributors working within Her Majesty's Government must review the [Civil Service
+Code][civil-service-code], and are expected to follow it in their contributions.
 
 ## Contributor Covenant Code of Conduct
 
@@ -66,15 +65,15 @@ for other behaviours that they deem inappropriate, threatening, offensive, or ha
 This Code of Conduct applies within all project spaces, and it also applies when an
 individual is representing the project or its community in public spaces. Examples of
 representing a project or community include using an official project e-mail address,
-posting via an official social media account, or acting as an appointed representative
-at an online or offline event. Representation of a project may be further defined and
-clarified by project maintainers.
+posting using an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
 
 ### Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by
 contacting the project team at
-[gdsdatascience@digital.cabinet-office.gov.uk][email-address]. All complaints will be
+[gds-data-science@digital.cabinet-office.gov.uk][email-address]. All complaints will be
 reviewed and investigated and will result in a response that is deemed necessary and
 appropriate to the circumstances. The project team is obligated to maintain
 confidentiality with regard to the reporter of an incident. Further details of
@@ -88,12 +87,12 @@ project's leadership.
 
 This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant],
 version 1.4, available at
-[https://www.contributor-covenant.org/version/1/4/code-of-conduct.html][contributor-covenant-code-of-conduct],
+[https://www.contributor-covenant.org/version/1/4/code-of-conduct/][contributor-covenant-code-of-conduct],
 and the `alphagov` Code of Conduct available at
-[https://github.com/alphagov/.github/blob/master/CODE_OF_CONDUCT.md][alphagov-code-of-conduct].
+[https://github.com/alphagov/.github/blob/main/CODE_OF_CONDUCT.md][alphagov-code-of-conduct].
 
-[alphagov-code-of-conduct]: https://github.com/alphagov/.github/blob/master/CODE_OF_CONDUCT.md
+[alphagov-code-of-conduct]: https://github.com/alphagov/.github/blob/main/CODE_OF_CONDUCT.md
 [civil-service-code]: https://www.gov.uk/government/publications/civil-service-code/the-civil-service-code
 [contributor-covenant]: https://www.contributor-covenant.org
-[contributor-covenant-code-of-conduct]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-[email-address]: mailto:gdsdatascience@digital.cabinet-office.gov.uk
+[contributor-covenant-code-of-conduct]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/
+[email-address]: mailto:gds-data-science@digital.cabinet-office.gov.uk

CONTRIBUTING.md

@@ -1,57 +1,57 @@
 # Contributing
 
 We love contributions! We've compiled this documentation to help you understand our
-contributing guidelines. If you still have questions, please
-[contact us][email-address] and we'd be happy to help!
+contributing guidelines. [If you still have questions, please contact us][email] and
+we'd be happy to help!
 
 ## Code of Conduct
 
-Please read [`CODE_OF_CONDUCT.md`][code-of-conduct] before contributing.
+[Please read `CODE_OF_CONDUCT.md` before contributing][code-of-conduct].
 
 ## Getting started
 
-To start contributing, first ensure your system meets the
-[requirements][readme-requirements]. Next, install the required Python packages, and
-[pre-commit hooks][pre-commit] using:
+To start contributing, install the required Python packages, and [pre-commit
+hooks][pre-commit] using:
 
 ```shell
-make requirements
+pip install -r requirements.txt
+pre-commit install
 ```
 
-It is better to use the above make command, rather than
-`pip install -r requirements.txt` and `pre-commit install`, as the command will ensure
-your pre-commit hooks are up-to-date with any changes made.
+or the `make` command:
 
-The pre-commit hooks are a security feature to ensure no
-secrets[^1], large data files, and Jupyter notebook outputs are
-accidentally committed into the repository. For more information about the pre-commit
-hooks used in this repository, see the [documentation][docs-pre-commit-hooks].
+```shell
+make requirements
+```
 
+The pre-commit hooks are a security feature to ensure, for example, no secrets[^1], and
+large data files are accidentally committed into the repository. [For more information
+on pre-commit hooks see our documentation][docs-pre-commit-hooks].
 
-[^1]: [Only secrets of specific patterns are detected by the
-pre-commit hooks][docs-pre-commit-hooks-secrets-definition].
+[^1]: [Only secrets of specific patterns are detected by the pre-commit
+      hooks][docs-pre-commit-hooks-secrets-definition].
 
 ## Code conventions
 
-We mainly follow [The GDS Way][gds-way] in our code conventions.
+[We mainly follow the GDS Way in our code conventions][gds-way].
 
 ### Git and GitHub
 
-We use Git to version control the source code; please read [The GDS Way][gds-way-git]
-for further details, including information about writing good commit messages, using
-`git rebase` for local branches, and `git merge --no-ff` for merges, as well as the
-entry on `git push --force-with-lease` instead of `git push -f`.
+We use Git to version control the source code. [Please read the GDS Way for details on
+Git best practice][gds-way-git]. This includes how to write good commit messages, use
+`git rebase` for local branches and `git merge --no-ff` for merges, as well as using
+`git push --force-with-lease` instead of `git push -f`.
 
-If you want to modify the `.gitignore` files, see the template
-[documentation][docs-updating-gitignore] for further details.
+[If you want to modify the `.gitignore` files, see the template
+documentation][docs-updating-gitignore] for further details.
 
 Our source code is stored on GitHub at
 [https://github.com/ukgovdatascience/govcookiecutter][govcookiecutter]. Pull requests
 into `main` require at least one approved review.
 
 ### Python
 
-For Python code, we follow [The GDS Way Python style guide][gds-way-python] with a line
+For Python code, [we follow the GDS Way Python style guide][gds-way-python] with a line
 length of 88; the flake8 pre-commit hook should help with this!
 
 ### Markdown
@@ -60,20 +60,20 @@ Local links can be written as normal, but external links should be referenced at
 bottom of the Markdown file for clarity. For example:
 
 ```md
-Use a local link to reference the [`README.md`](./README.md) file, but an external
-link for [GOV.UK][gov-uk].
+Use a local link to reference the [`README.md`](./README.md) file, but an external link
+for [GOV.UK][gov-uk].
 
 [gov-uk]: https://www.gov.uk/
 ```
 
-We also try to wrap Markdown to a line length of 88 characters, but this is not
-strictly enforced in all cases, for example with long hyperlinks.
+We also try to wrap Markdown to a line length of 88 characters. This is not strictly
+enforced in all cases, for example with long hyperlinks.
 
 ## Testing
 
-Tests are written using the [pytest][pytest] framework, with its configuration in the
+[Tests are written using the `pytest` framework][pytest], with its configuration in the
 `pyproject.toml` file. Note, only tests in the `tests`, and
-`{{ cookiecutter.repo_name }}/tests` folders are executed. To run the tests, execute
+`{{ cookiecutter.repo_name }}/tests` folders folder are run. To run the tests, enter
 the following command in your terminal:
 
 ```shell
@@ -82,50 +82,58 @@ pytest
 
 ### Code coverage
 
-Code coverage of Python scripts is measured using the [`coverage`][coverage] Python
-package; its configuration can be found in `pyproject.toml`. Note coverage only extends
-to Python scripts in the `hooks`, and `{{ cookiecutter.repo_name }}/src` folders.
+[Code coverage of Python scripts is measured using the `coverage` Python
+package][coverage]; its configuration can be found in `pyproject.toml`. Note coverage
+only extends to Python scripts in the `hooks`, and
+`{{ cookiecutter.repo_name }}/src` folders.
 
-To run code coverage, and view it as an HTML report, execute the following commands in
+To run code coverage, and view it as an HTML report, enter the following command in
 your terminal:
 
 ```shell
 coverage run -m pytest
 coverage html
 ```
 
-The HTMl report can be accessed at `htmlcov/index.html`.
+or use the `make` command:
+
+```shell
+make coverage_html
+```
+
+The HTML report can be accessed at `htmlcov/index.html`.
 
 ## Documentation
 
-We write our documentation in [MyST Markdown][myst] for use in Sphinx. This is mainly
+[We write our documentation in MyST Markdown for use in Sphinx][myst]. This is mainly
 stored in the `docs` folder, unless it's more appropriate to store it elsewhere, like
 this file.
 
-[Please read our guidance on how to write Sphinx
-documentation][docs-write-sphinx-documentation], and build it into a searchable website.
+[Please read our guidance on how to write accessible
+documentation][docs-write-accessible-documentation], as well as our [guidance on
+writing Sphinx documentation][docs-write-sphinx-documentation]. This allows you to
+build the documentation into an accessible, searchable website.
 
 ## Organisational frameworks
 
 Organisational frameworks are stored in the
-`.govcookiecutter/organisational_frameworks` folder. If you would like to add your own
-organisation's framework, follow the [instructions][docs-govcookiecutter-frameworks] in
+`.govcookiecutter/organisational_frameworks` folder. [If you would like to add your own
+organisation's framework, follow the instructions][docs-govcookiecutter-frameworks] in
 the `README.md` file in that folder.
 
 [code-of-conduct]: ./CODE_OF_CONDUCT.md
 [coverage]: https://coverage.readthedocs.io/
-[docs-govcookiecutter-frameworks]: {{ cookiecutter.repo_name }}/.govcookiecutter/organisational_frameworks/README.md
+[docs-govcookiecutter-frameworks]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/.govcookiecutter/organisational_frameworks/README.md
 [docs-pre-commit-hooks]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/docs/contributor_guide/pre_commit_hooks.md
 [docs-pre-commit-hooks-secrets-definition]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/docs/contributor_guide/pre_commit_hooks.md#definition-of-a-secret-according-to-detect-secrets
 [docs-updating-gitignore]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/docs/contributor_guide/updating_gitignore.md
+[docs-write-accessible-documentation]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/docs/contributor_guide/writing_accessible_documentation.md
 [docs-write-sphinx-documentation]: ./%7B%7B%20cookiecutter.repo_name%20%7D%7D/docs/contributor_guide/writing_sphinx_documentation.md
-[email-address]: mailto:gdsdatascience@digital.cabinet-office.gov.uk
+[email]: mailto:gds-data-science@digital.cabinet-office.gov.uk
 [gds-way]: https://gds-way.cloudapps.digital/
 [gds-way-git]: https://gds-way.cloudapps.digital/standards/source-code.html
 [gds-way-python]: https://gds-way.cloudapps.digital/manuals/programming-languages/python/python.html#python-style-guide
 [govcookiecutter]: https://github.com/ukgovdatascience/govcookiecutter
-[govcookiecutter-frameworks]: {{ cookiecutter.repo_name }}/.govcookiecutter/organisational_frameworks
 [myst]: https://myst-parser.readthedocs.io/
 [pre-commit]: https://pre-commit.com/
 [pytest]: https://docs.pytest.org/
-[readme-requirements]: ./README.md#requirements-to-create-a-cookiecutter-template

Makefile

@@ -19,7 +19,7 @@ requirements:
 	python -m pip install -r requirements.txt
 	pre-commit install
 
-## Create a `docs/_build` folder, if it doesn't exist. Otherwise delete any sub-folders and their contents within it
+## Create a `docs/_build` folder, if it does not exist. Otherwise delete any sub-folders and their contents within it
 prepare_docs_folder:
 	if [ ! -d "./docs/_build" ]; then mkdir ./docs/_build; fi
 	find ./docs/_build -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} \;
@@ -32,7 +32,7 @@ docs: prepare_docs_folder requirements
 docs_check_external_links: prepare_docs_folder requirements
 	sphinx-build -b linkcheck ./docs ./docs/_build
 
-## Create an `example` folder, if it doesn't exist. Otherwise delete any subfolders and their contents within it
+## Create an `example` folder, if it does not exist. Otherwise delete any subfolders and their contents within it
 prepare_example_folder:
 	if [ ! -d "./example" ]; then mkdir ./example; fi
 	find ./example -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} \;