Skip to content

Commit 3f395e0

Browse files
masl2masl2
committed
CCM-11207: documentation overview and structure for developer and consumer guidance
1 parent 2d3d128 commit 3f395e0

29 files changed

+457
-28
lines changed

‎CONTRIBUTING.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Contributing to NHS Notify Supplier API
2+
3+
## Feature Branches
4+
5+
All changes to the repo must be created on a feature branch and submitted for peer review as a Pull Request (PR) via GitHub.
6+
7+
Feature branch names should follow the format below:
8+
9+
```text
10+
feature/${jira-ticket-number}_${precis-of-branch-purpose}
11+
```
12+
13+
e.g.
14+
15+
```text
16+
feature/CCM-11207_documentation
17+
```
18+
19+
## Main Branch
20+
21+
You are not permitted to push directly to the remote `main` branch in GitHub.
22+
23+
Changes to `main` when require approval(s) recorded on your PR.
24+
Required approvers are controlled by the CODEOWNERS file but in summary:
25+
26+
- Infrastructure changes should be reviewed by DevOps team members
27+
- Workflow/action changes should be reviewed by Maintainers of the repo
28+
- All other changes should be review by NHS API Development team members
29+
30+
Merges should only take place:
31+
32+
- They are intended for the next release cycle
33+
- All CI workflows have completed successfully
34+
35+
## Coding Standards
36+
37+
Your PR must follow all agreed coding standards for the project. Terraform and CI/CD standards are listed in sections below.
38+
39+
### GitHooks
40+
41+
GitHooks are available within this repo to help maintain standards and protect against e.g. secrets disclosure
42+
43+
GitHooks **must** be configured and run on commits before pushing to remote. Refer to the developer documentation for more information if required.
44+
45+
## Testing Your Branch
46+
47+
You can test your branch in a dynamic environment prior to merging to `main`. These are created as part of the `cicd-1-pull-request.yaml` workflow, triggered when a PR is created or updated.

‎docs/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,8 @@ vendor
77
*Zone.Identifier
88
node_modules
99
_config.version.yml
10+
11+
# Generated or copied from other repo resources
12+
_includes/components/nhs-notify-supplier-api.html
13+
_includes/components/contributing.md
14+
assets/diagrams/types.md

‎docs/Makefile‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ define baseurlparam =
1919
$(if $(BASE_URL),-- --baseurl $(BASE_URL),-- --baseurl "")
2020
endef
2121

22-
build: version
22+
build: version .generate-dependencies
2323
npm run build $(baseurlparam)
2424

25-
debug: version
25+
debug: version .generate-dependencies
2626
npm run debug
2727

2828
version:
@@ -38,3 +38,6 @@ version:
3838
fi
3939

4040
echo "{ \"schemaVersion\": 1, \"label\": \"version\", \"message\": \"$$(head -n 1 .version 2> /dev/null || echo unknown)\", \"color\": \"orange\" }" > version.json
41+
42+
.generate-dependencies:
43+
npm run generate-dependencies --if-present

‎docs/_config.yml‎

Lines changed: 64 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,69 @@ url: "https://nhsdigital.github.io" # the base hostname & protocol for your site
2828
collections_dir: collections
2929

3030
collections:
31-
notify-repos:
31+
architecture:
3232
output: true
3333
sort_by: order
34+
repos:
35+
output: true
36+
sort_by: order
37+
consumers:
38+
output: true
39+
sort_by: order
40+
developers:
41+
output: true
42+
sort_by: order
43+
44+
just_the_docs:
45+
collections:
46+
consumers:
47+
name: API Consumers
48+
developers:
49+
name: API Developers
50+
repos:
51+
name: Notify Repositories
52+
# Exclude the collection from the navigation
53+
# Supports true or false (default)
54+
nav_exclude: false
55+
# Fold the collection in the navigation
56+
# Supports true or false (default)
57+
nav_fold: false # note: this option is new in v0.4
58+
# Exclude the collection from the search
59+
# Supports true or false (defaul
60+
search_exclude: false
61+
architecture:
62+
name: Architecture & Design
63+
guides:
64+
name: Guides & How Tos
65+
66+
defaults:
67+
- scope:
68+
path: ""
69+
type: "repos"
70+
values:
71+
layout: "notify-repo"
72+
is_not_draft: false
73+
owner: NHS Notify
74+
author: NHS Notify
75+
last_modified_date: 2025-10-08
76+
- scope:
77+
path: ""
78+
type: "onboarding"
79+
values:
80+
layout: "page"
81+
is_not_draft: false
82+
owner: NHS Notify
83+
author: NHS Notify
84+
last_modified_date: 2025-10-08
85+
- scope:
86+
path: ""
87+
type: "developers"
88+
values:
89+
layout: "page"
90+
is_not_draft: false
91+
owner: NHS Notify
92+
author: NHS Notify
93+
last_modified_date: 2025-10-08
3494

3595
# Build settings
3696
theme: just-the-docs
@@ -45,15 +105,15 @@ mermaid:
45105
version: "10.9.1"
46106

47107
aux_links:
48-
"NHS Notify Repo Template on GitHub":
49-
- "//github.com/NHSDigital/nhs-notify-repository-template"
108+
"NHS Notify Supplier API Template on GitHub":
109+
- "//github.com/NHSDigital/nhs-notify-supplier-api"
50110

51111
aux_links_new_tab: false
52112

53113
# Footer "Edit this page on GitHub" link text
54114
gh_edit_link: true # show or hide edit this page link
55115
gh_edit_link_text: "Edit this page on GitHub."
56-
gh_edit_repository: "https://github.com/NHSDigital/nhs-notify-repository-template" # the github URL for your repo
116+
gh_edit_repository: "https://github.com/NHSDigital/nhs-notify-supplier-api" # the github URL for your repo
57117
gh_edit_branch: "main" # the branch that your docs is served from
58118
# gh_edit_source: docs # the source that your files originate from
59119
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

‎docs/_includes/notify-repo-list.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<h2>Repository List</h2>
2+
3+
<ul>
4+
{% for repo in site.repos %} {% if repo.order > 0 %}
5+
<li>
6+
<a href="{{site.baseurl}}/repos/{{repo.repo-name}}.html">
7+
{{ repo.repo-name }} - {{ repo.name }}
8+
</a>
9+
</li>
10+
{% endif %} {% endfor %}
11+
</ul>

‎docs/_includes/notify-repo-table.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<h2>Repository List</h2>
2+
3+
<table>
4+
<tr>
5+
<th>Repository Name</th>
6+
<th>More Info</th>
7+
</tr>
8+
{% for repo in site.repos %} {% if repo.order > 0 %}
9+
<tr>
10+
<td>{{repo.repo-name}}</td>
11+
<td>
12+
<a href="{{site.baseurl}}/repos/{{repo.repo-name}}.html">
13+
{{ repo.name }} - {{ repo.description }}
14+
</a>
15+
</td>
16+
</tr>
17+
{% endif %} {% endfor %}
18+
</table>

‎docs/_layouts/home.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
layout: default
3+
---
4+
5+
{{ content }}

‎docs/_layouts/notify-repo.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
layout: page
3+
---
4+
5+
<!-- markdownlint-disable MD041 -->
6+
7+
<dl>
8+
<dt>Repository</dt>
9+
<dd><a href="https://github.com/NHSDigital/{{page.repo-name}}">https://github.com/NHSDigital/{{page.repo-name}}</a></dd>
10+
11+
<dt>Owners</dt>
12+
{% for owner in page.owners %}
13+
<dd> <a href="http://github.com/{{owner}}">{{owner}}</a> </dd>
14+
{% endfor %}
15+
</dl>
16+
17+
{{ content }}
18+
19+
{% include notify-repo-list.html %}
20+
21+
<!-- markdownlint-enable MD041 -->

‎docs/collections/_consumers/acceptance.md‎

Whitespace-only changes.

‎docs/collections/_consumers/getting-started.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: API Consumers - Getting Started
3+
order: 0
4+
nav_order: 1
5+
has_children: false
6+
has_toc: false
7+
---

0 commit comments

Comments
 (0)