Revise documentation

[ESKYoung]

Summary

Revise documentation to include further detail on the cookiecutter package, and how to modify the structure of govcookiecutter. Fixed incorrect contact email address.

Added tests to check for broken links in the Sphinx documentation - ensures future releases of govcookiecutter have the correct links throughout the documentation.

Added information on cruft, which could help future projects generated from govcookiecutter stay up-to-date with any changes we release here.

Also refactor documentation (Markdown/reStructuredText files only, predominately excluding CODE_OF_CONDUCT.md and CONTRIBUTING.md) so that it is more accessible. Accessibility checks include:

• building documentation against govuk-tech-docs-sphinx-theme [currently private, but soon to be public repository]
• checking against WAVE Web Accessibility Evaluation Tool
• checking link test is descriptive
• checking hierarchy of page headings
• removing italics, and bold text, and only using block capitals for placeholders in code examples
• checking for accessible language
  • using alex.js
  • replacing instances of click with select or choose
  • removing latin phrases, i.e. ad hoc, via
  • using GOV.UK inclusive language
  • replacing negative contractions
  • aiming not to have long sentences or paragraphs (25 words per sentence; 5 lines per paragraph)
  • checking for unique titles in documentation
  • checking diagrams and images for alt text as well as surrounding contextual text, removing diagrams/images that do not add anything to a user's understanding, removing screenshots if possible, use accessible SVGs
  • checking for inaccessible formats

Once govuk-tech-docs-sphinx-theme goes live (July? Preview site here), I will raise a new PR separately to publish the govcookiecutter documentation on GitHub Pages, adding a corresponding accessibility statement.

@alexander-newton - for interest!

Checklists

This pull/merge request meets the following requirements:

• Code runs
• Developments are secure and ethical
• You have made proportionate checks that the code works correctly
• You have tested the build of the template
• Test suite passes
• Minimum usable documentation written in the docs folder

Comments have been added below around the incomplete checks.

[ESKYoung]

Apologies, missed a few bullet list fixes for style formatting, hence the force push.

[codecov]

Codecov Report

Merging #33 (362ec5d) into main (b4adf6c) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##              main       #33   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            2         2           
  Lines           29        29           
=========================================
  Hits            29        29           

Impacted Files	Coverage Δ
hooks/pre_gen_project.py	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b4adf6c...362ec5d. Read the comment docs.

[ESKYoung]

Added govuk-tech-docs-sphinx-theme as the Sphinx theme. This allows us to deploy this documentation onto GitHub Pages.

Will raise a separate PR later to include the theme as an option for all future projects build from govcookiecutter.

[nacnudus]

Review progress

I ran the GitHub Action on release locally (instructions below), which rendered the docs. To help check that the changes are as expected, here's a screenshot with the window narrowed to resemble a mobile device.

Here's how they look currently:

Running GitHub actions locally

Using act:

# From the root directory of this repository, run the action and don't stop the container
act --reuse release
# Find the name of the container
docker ps
# Copy the `docs/_build` folder of rendered docs to the local system.
docker cp <name_of_container>:$(pwd)/docs/_build docs/
# Browse the docs/build/index.html in a web browser

[nacnudus]

A live checklist of what I have checked, with remarks inline.

• Revise documentation to include further detail on the cookiecutter package, and how to modify the structure of govcookiecutter.
• Fixed incorrect contact email address.
• Added tests to check for broken links in the Sphinx documentation - ensures future releases of govcookiecutter have the correct links throughout the documentation.
• Added information on cruft, which could help future projects generated from govcookiecutter stay up-to-date with any changes we release here.

Also refactor documentation (Markdown/reStructuredText files only, predominately excluding CODE_OF_CONDUCT.md and CONTRIBUTING.md) so that it is more accessible. Accessibility checks include:

• building documentation against govuk-tech-docs-sphinx-theme [currently private, but soon to be public repository]
• checking against WAVE Web Accessibility Evaluation Tool I couldn't get the WAVE browser extension to work with the locally rendered site
• checking link test is descriptive I wrote a script to list the link text of all links, and they're all descriptive where appropriate
• checking hierarchy of page headings I wrote a script to check for skipped levels between headings, and there are none
• removing italics, and bold text, and only using block capitals for placeholders in code examples **I searched the markdown with regex to find bold, italics, block capitals, {{ and << (previous indications of placeholders)
• checking for accessible language
  • using alex.js
  • replacing instances of click with select or choose
  • removing latin phrases, i.e. ad hoc, via A few instances remain of "i.e.", "e.g." and "via"
  • using GOV.UK inclusive language
  • replacing negative contractions An instance remains in each makefile (not technically part of the docs, but probably worth doing in this PR)
  • aiming not to have long sentences or paragraphs (25 words per sentence; 5 lines per paragraph) **A few slightly longer sentences -- see following comment)
  • checking for unique titles in documentation ** checked with a script**
  • checking diagrams and images for alt text as well as surrounding contextual text, removing diagrams/images that do not add anything to a user's understanding, removing screenshots if possible, use accessible SVGs There don't seem to be any images
  • checking for inaccessible formats

Once govuk-tech-docs-sphinx-theme goes live (July? Preview site here), I will raise a new PR separately to publish the govcookiecutter documentation on GitHub Pages, adding a corresponding accessibility statement.

• 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

[nacnudus]

Long sentences (found by tokenising into paragraphs, then sentences, then words):

1. README.md: the first sentence under ## Acknowledgements.
2. docs/contributing_guide/modify_govcookiecutter.md: sentences beginning "Whilst", and "The constant".
3. docs/accessibility.md: sentence beginning "We're always"
4. CONTRIBUTING.md: sentence beginning "We also try"
5. CODE_OF_CONDUCT.md: sentences beginning "Contributors to", "In the interest" (not sure that one is fixable), "Project maintainers" (both sentences), "Examples of representing", "This code of conduct applies", "Project maintainers who do not follow"
6. {{ cookiecutter.repo_name }}/notebooks/README.md
7. {{ cookiecutter.repo_name }}/docs/contributor_guide/pre_commit_hooks.md: sentences beginning, "It's strongly", "In either case",
8. {{ cookiecutter.repo_name }}/data/README.md: sentence beginning, "The folder"
9. {{ cookiecutter.repo_name }}/docs/aqa/aqa_plan.md: sentence beginning, "This is a living"

[nacnudus]

This represents a lot of careful work, thank you @ESKYoung!

I have skim-read the diffs to check that nothing has accidentally been pasted in and committed. Most of the changes seem to be the odd word here and there, to meet accessibility guidelines, alexjs, etc. There are some structural changes, such as moving chunks of text into separate files -- I haven't read those carefully, so I trust that nothing has been accidentally lost in the transfer.

I ran alexjs myself. I couldn't get the WAVE browser addin to work with the locally rendered website, and I haven't created my own repo to render it online, so I trust that WAVE's suggestions have been addressed.

For some textual checks, such as heading hierarchy and sentence length, I wrote R scripts to help, and have mentioned things that turned up. They're pretty trivial.

So all in all, a great PR. Approved!

[ESKYoung]

@nacnudus thanks for the thorough review!

I've made the changes in commit 5401bad, except for the following long sentences:

• CODE_OF_CONDUCT.md: All remain unfixed except for the "Contributors to" paragraph. The remaining are difficult to modify given the context. As we "aim" to have short sentences/paragraphs, I'm going to leave this for now.

I've also added some guidance on writing accessible documentation that captures the above checklist. Grateful if you could have a quick skim!

[nacnudus]

Thanks @ESKYoung! Just one typo, otherwise good to go.

[ESKYoung]

Thanks for your very thorough review @nacnudus! Merging! 🚀