Merge branch 'anchit-edits-reviewed-marcus' into develop

docs/_assets/_snippets/live-usage-warning.md

@@ -0,0 +1,6 @@
+!!! danger "IMPORTANT: **You should never need to generate an NHS Number for a live system**"
+    Live NHS, CHI, H&C and IHI numbers are _always_ generated by some kind of central authority or registry, such as the NHS Spine in England, and they are assigned to patients, often at or near birth or at the point of becoming a user of that health system.
+
+    Unless you represent a central health authority, you should not need to generate an NHS Number for a live system. If you are a patient, you should never need to generate an NHS Number for yourself.
+
+    This package is intended for use in testing and development environments where you need to generate NHS Numbers for testing, research purposes, or synthetic data generation.

docs/_assets/_snippets/scottish-chi-number.md

@@ -0,0 +1,2 @@
+!!! note "Scottish CHI Number validation"
+    At present, this library does not reliably validate Scottish CHI Numbers. This is because the first 6 digits of a Scottish CHI Number must be a valid DDMMYY Date of Birth, and this library does not currently check for this. At the moment, only the correct number range is checked for.

docs/_assets/_stylesheets/extra.css

@@ -0,0 +1,46 @@
+:root {
+    --nhs-core-blue: #005EB8;
+    --nhs-core-white: #FFFFFF;
+    --md-accent-fg-color: var(--nhs-core-blue);
+    --md-primary-fg-color--dark: var(--nhs-core-blue);
+    --md-typeset-a-color: var(--nhs-core-blue);
+}
+
+.md-header__ellipsis .md-ellipsis {
+    font-size: 1.5rem;
+}
+
+/* nav   */
+
+/* mobile nav sidebar */
+@media screen and (max-width: 76.1875em) {
+    .md-nav--primary .md-nav__title[for=__drawer] {
+        background-color: white;
+        color: black;
+    }
+}
+
+[dir=ltr] .md-header__title {
+    margin-left: 0.1rem;
+}
+
+.md-header__button.md-logo >svg {
+    height: 2rem;
+    fill: var(--nhs-core-white)
+}
+
+.md-banner {
+    display: flex;
+}
+
+.md-banner__inner.md-grid.md-typeset{
+    max-height: 1rem;
+}
+
+.md-header, .md-tabs {
+    background-color: var(--nhs-core-blue);
+}
+
+.md-nav__item .md-nav__link--active {
+    color: var(--nhs-core-blue);
+}

docs/changelog.md

@@ -3,8 +3,15 @@ title: Changelog
 authors: Dr Marcus Baw
 ---
 
+## 1.3.4
+- Revert of the new logo, minor edits to the documentation, accepted Anchit PR
+- Reverted to plain code rather than Carbon for the code snippets.
+- No changes to Python code
+
 ## 1.3.3
 
+- Aesthetic documentation updates
+
 ## 1.3.2
 
 * GitHub action for CI/CD to publish to live PyPi

docs/contributors.md

@@ -5,11 +5,11 @@ authors: Dr Marcus Baw
 
 ## Acknowledgements
 
-This package is a collaboration between a number of individuals, groups and teams, who were each separately maintaining some kind of NHS Number Python package. We felt that rather than having several packages with overlapping functionality, it would be better to combine our efforts into a single package.
+This package is a collaboration between several individuals, groups and teams, each separately maintaining some NHS Number Python package. Rather than having several packages with overlapping functionality, it was thought that combining efforts into a single package would be better.
 
-The package derives from code written by Andy Law at the Roslin Institute, and in an effort to place it under the aegis of an Organisation on GitHub, it has been adopted by the [Faculty of Clinical Informatics](https://www.facultyofclinicalinformatics.org.uk/), with the collective aim to develop it into the canonical NHS Number package for Python.
+The package derives from code written by Andy Law at the Roslin Institute, and to place it under the aegis of an Organisation on GitHub, it has been adopted by the [Faculty of Clinical Informatics](https://www.facultyofclinicalinformatics.org.uk/), with the collective aim to develop it into the canonical NHS Number package for Python.
 
-### Authors and contributors
+## Authors and contributors
 
 - [Andy Law](https://github.com/andylaw) - author of the PyPi package [nhs-number](https://pypi.org/project/nhs-number/), head of research computing at The Roslin Institute.
 

docs/developing.md

@@ -1,5 +1,4 @@
 ---
-title: Developing
 authors: Dr Marcus Baw
 ---
 
@@ -11,7 +10,7 @@ authors: Dr Marcus Baw
 ├── tests/              # Python package tests
 ├── __init__.py
 ├── LICENSE             # MIT License
-├── mkdocs.yml          # configuration file for the Material for MkDocs documentation site
+├── mkdocs.yml          # Configuration file for the Material for MkDocs documentation site
 ├── netlify.toml        # Netlify build file - required for Netlify to build the documentation site
 ├── pyproject.toml      # Poetry configuration file - defines dependencies, etc
 ├── pytest.ini          # pytest configuration file - defines test discovery, etc
@@ -21,36 +20,6 @@ authors: Dr Marcus Baw
 └── setup.cfg
 ```
 
-## Useful URLs
-
-### Github :simple-github:
-
-`nhs-number` GitHub repo <https://github.com/uk-fci/nhs-number>
-
-### PyPi :simple-pypi:
-
-`nhs-number` on PyPI <https://pypi.org/project/nhs-number/>
-`nhs-number` on **Test** PyPi <https://test.pypi.org/project/nhs-number/>
-
-### Netlify :simple-netlify:
-
-<https://app.netlify.com/sites/nhs-number/overview>
-
-### uk-fci.tech domain :material-domain:
-
-The `uk-fci.tech` domain is managed on NameCheap by @pacharanero
-
-## Documentation
-
-The main documentation site is at <https://nhs-number.uk-fci.tech>. Pushes of code to the `main` branch will trigger a publication to Netlify automatically.
-
-Non-`main` branches of the documentation are automatically published to Netlify for review purposes:
-
-* `develop` -> <https://develop.nhs-number.uk-fci.tech>
-* `staging` -> <https://staging.nhs-number.uk-fci.tech>
-
-When developing the documentation site, we recommend the use of a linter such as [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) for VSCode to standardise formatting.
-
 ## Testing
 
 This project uses `pytest` for testing. The test suite can be run with:
@@ -59,18 +28,20 @@ This project uses `pytest` for testing. The test suite can be run with:
 poetry run pytest
 ```
 
-## Building locally
+<!-- ## Building locally @pacharanero is something meant to go here? -->
 
 ## Publishing to PyPi
 
+This project uses [Poetry](https://python-poetry.org/docs/) for dependency management and packaging.
+
+Any edit **MUST** have a new version number otherwise it will be rejected by PyPi.
+
+To publish a new version to PyPi, update the version number in `pyproject.toml`.
+
+Also add a note to the `docs/changelog.md` file to explain the updates.
+
 Publication to PyPi is handled by GitHub Actions. The workflows are defined in the `.github/workflows` folder.
 
 Pushes of code to the `staging` branch will trigger a publication to Test PyPi.
 
 Pushes of code to the `main` branch will trigger a publication to live PyPi.
-
-## External Documentation References
-
-* Poetry <https://python-poetry.org/docs/>
-* Material for MkDocs <https://squidfunk.github.io/mkdocs-material/getting-started/>
-* Netlify available build environments <https://docs.netlify.com/configure-builds/available-software-at-build-time/>

docs/documentation.md

@@ -0,0 +1,18 @@
+---
+authors: Dr Marcus Baw, Dr Anchit Chandran
+---
+
+The main documentation site is at <https://nhs-number.uk-fci.tech>. Pushes of code to the `main` branch will automatically trigger a publication to Netlify.
+
+Non-`main` branches of the documentation are automatically published to Netlify for review purposes:
+
+* `develop` -> <https://develop.nhs-number.uk-fci.tech>
+* `staging` -> <https://staging.nhs-number.uk-fci.tech>
+
+## Material for MkDocs
+
+We use [MkDocs](https://www.mkdocs.org/) along with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
+
+You can suggest changes directly through PRs.
+
+When developing the documentation site, we recommend the use of a linter such as [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) for VSCode to standardise formatting.

docs/index.md

@@ -3,29 +3,46 @@
 ```python
 >>> import nhs_number
 
-# test a valid number
->>> nhs_number.is_valid('1234567891')
+# Validation
+>>> nhs_number.is_valid('469 819 4180')
 True
+
+# Generation (for testing purposes)
+>>> nhs_number.generate(quantity=5, for_region=nhs_number.REGION_ENGLAND)
+['6239431915', '7634140872', '4069990771', '4453051670', '4843474045']
+
+# Normalisation
+>>> nhs_number.normalise_number("406-999-0771")
+'4069990771'
 ```
 
+  <figcaption>Validation, generation and normalisation of NHS Numbers</figcaption>
+
 A Python package to provide utilities for NHS Numbers, including validity checks, normalisation, and generation.
 
-This package is a collaboration between a number of individuals, groups and teams, who were each separately maintaining some kind of NHS Number Python package. See [Contributors](./contributors.md) for more information.
+While validating an NHS Number is straightforward to achieve in code, it seems wasteful for developers to implement their own solutions. Further, many developers are likely unaware of the various rules and nuances of NHS/CHI/H&C Numbers across the UK Nations.
 
-While validating an NHS Number is not particularly difficult to achieve in code, it seems wasteful for developers to have to implement their own solutions, and it is likely that many developers will not be aware of the various rules and nuances of NHS/CHI/H&C Numbers across the UK Nations. This package aims to provide a single, well-maintained, and well-documented solution for all developers to use.
+This package aims to provide a single, well-maintained, well-documented solution for all developers.
+
+`nhs-number` is a collaboration between several individuals, groups and teams, each separately maintaining an NHS Number Python package. See [Contributors](./contributors.md) for more information.
 
 ## Features
 
-- Validation of NHS Numbers using the check-digit algorithm.
-- Normalisation of NHS Numbers from various string formats to a standard 10-digit string format.
-- Additional details and information on an NHS number such as the region it is valid for, and the reason it is not valid, if invalid.
-- Generation of valid and invalid NHS Numbers for testing purposes, for any selected Region. Note that you should **never** need to generate an NHS Number for a live system (See [Important Note](#important-note) below)
+- **Validation** of NHS Numbers using the check-digit algorithm.
+- **Generation** of valid and invalid NHS Numbers for testing purposes, for any selected `Region`.
+- **Normalisation** of NHS Numbers from various string formats to a standard 10-digit string format.
+- Additional details and information on an NHS number, such as the region for which it's valid, and the reason for invalidity, if invalid.
+
+--8<--
+docs/_assets/_snippets/live-usage-warning.md
+--8<--
 
-!!! warning "Important note about Scottish CHI Number validation"
-At present this library does not reliably validate Scottish CHI Numbers. This is because the first 6 digits of a Scottish CHI Number must be a valid DDMMYY Date of Birth, and this library does not currently check for this. At the moment only the correct number range is checked for.
+--8<--
+docs/_assets/_snippets/scottish-chi-number.md
+--8<--
 
 ## Roadmap
 
-- Additional validation for Scottish CHI numbers to ensure the first 6 digits are a valid DDMMYY Date of Birth.
-- Generation of valid Scottish CHI numbers along same rules.
+- Additional validation for Scottish CHI numbers to ensure the first 6 digits are a valid `DDMMYY` Date of Birth.
+- Generation of valid Scottish CHI numbers along the same rules.
 - Validation and generation of [IHI Numbers for the Republic of Ireland](ihi-ireland.md), subject to contributors wanting to collaborate on this, and there being a demand for implementation.

docs/installation.md

@@ -1,10 +1,8 @@
 ---
-title: nhs-number
+title: Install
 authors: Dr Marcus Baw
 ---
 
-## Installation
-
 To install using `pip`:
 
 ```bash