Skip to content

Commit ba809f1

Browse files
masl2masl2
authored
CCM-11207 Generate docs, overviews, placeholders, publish (#190)
* CCM-11207: documentation overview and structure for developer and consumer guidance * CCM-11207: more pages & placeholders * CCM-11207: ensure all deps * CCM-11207: change deploy to use jekyll site * CCM-11207: ensure directories present * CCM-11207: need a spec to gen from * CCM-11207: rename generate-includes to avoid impacting other CI * CCM-11207: missed rename * CCM-11207: remove the repos entry * CCM-11207: review comments: spelling and repo changes * CCM-11207: fix title
1 parent b403215 commit ba809f1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+2157
-84
lines changed

‎.github/actions/build-docs/action.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ runs:
1414
node-version: 18
1515
- name: Npm cli install
1616
working-directory: .
17-
run: npm ci -w docs
17+
run: npm ci
1818
shell: bash
1919
- name: Setup Ruby
2020
uses: ruby/[email protected]

‎.github/workflows/cicd-3-deploy.yaml‎

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -101,37 +101,15 @@ jobs:
101101
env:
102102
GH_TOKEN: ${{ github.token }}
103103
run: |
104-
gh release download ${{steps.get-asset-version.outputs.release_version}} -p sdk-swagger-docs-*.tar --output artifact.tar
104+
gh release download ${{steps.get-asset-version.outputs.release_version}} -p jekyll-docs-*.tar --output artifact.tar
105105
106106
- uses: actions/upload-artifact@v4
107107
with:
108-
name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
108+
name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
109109
path: artifact.tar
110110

111111
- name: Deploy to GitHub Pages
112112
id: deployment
113113
uses: actions/deploy-pages@v4
114114
with:
115-
artifact_name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
116-
117-
118-
### BELOW WAS THE DEFAULT USING THE JEKYLL BUILD
119-
120-
# - name: "Get release version"
121-
# id: download-asset
122-
# shell: bash
123-
# env:
124-
# GH_TOKEN: ${{ github.token }}
125-
# run: |
126-
# gh release download ${{steps.get-asset-version.outputs.release_version}} -p jekyll-docs-*.tar --output artifact.tar
127-
128-
# - uses: actions/upload-artifact@v4
129-
# with:
130-
# name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
131-
# path: artifact.tar
132-
133-
# - name: Deploy to GitHub Pages
134-
# id: deployment
135-
# uses: actions/deploy-pages@v4
136-
# with:
137-
# artifact_name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
115+
artifact_name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}

‎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.

‎README.md‎

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# NHS Notify Supplier API
1+
## NHS Notify Supplier API
22

33
[![1. CI/CD pull request](https://github.com/NHSDigital/nhs-notify-supplier-api/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/NHSDigital/nhs-notify-supplier-api/actions/workflows/cicd-1-pull-request.yaml)
44
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=NHSDigital_nhs-notify-supplier-api&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=NHSDigital_nhs-notify-supplier-api)
@@ -11,33 +11,32 @@ This repository documents the Supplier API specification and provides an SDK wit
1111

1212
## OAS Specifications
1313

14-
- [Current Version](specification/api/notify-supplier.yml)
15-
- [vNext](specification/api/notify-supplier-next.yml)
14+
- [Current Version](specification/api/notify-supplier-phase1.yml)
1615

1716
## Table of Contents
1817

1918
- [NHS Notify Supplier API](#nhs-notify-supplier-api)
20-
- [OAS Specifications](#oas-specifications)
21-
- [Table of Contents](#table-of-contents)
22-
- [API Consumers - Getting Started](#api-consumers---getting-started)
23-
- [OAS Specification](#oas-specification)
24-
- [Packages](#packages)
25-
- [Documentation](#documentation)
26-
- [SDK Assets](#sdk-assets)
27-
- [Examples](#examples)
28-
- [API Developers](#api-developers)
29-
- [Documentation](#documentation-1)
30-
- [pre built servers](#pre-built-servers)
31-
- [Setup](#setup)
32-
- [Prerequisites and Configuration](#prerequisites-and-configuration)
33-
- [SDKs](#sdks)
34-
- [Servers](#servers)
35-
- [Libs](#libs)
36-
- [Build](#build)
37-
- [GitHub Actions CI/CD](#github-actions-cicd)
38-
- [CI (Automatic)](#ci-automatic)
39-
- [CD (Manual)](#cd-manual)
40-
- [Licence](#licence)
19+
- [OAS Specifications](#oas-specifications)
20+
- [Table of Contents](#table-of-contents)
21+
- [API Consumers - Getting Started](#api-consumers---getting-started)
22+
- [OAS Specification](#oas-specification)
23+
- [Packages](#packages)
24+
- [Documentation](#documentation)
25+
- [SDK Assets](#sdk-assets)
26+
- [Examples](#examples)
27+
- [API Developers](#api-developers)
28+
- [Documentation](#documentation-1)
29+
- [pre built servers](#pre-built-servers)
30+
- [Setup](#setup)
31+
- [Prerequisites and Configuration](#prerequisites-and-configuration)
32+
- [SDKs](#sdks)
33+
- [Servers](#servers)
34+
- [Libs](#libs)
35+
- [Build](#build)
36+
- [GitHub Actions CI/CD](#github-actions-cicd)
37+
- [CI (Automatic)](#ci-automatic)
38+
- [CD (Manual)](#cd-manual)
39+
- [Licence](#licence)
4140

4241
## API Consumers - Getting Started
4342

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,6 @@ vendor
77
*Zone.Identifier
88
node_modules
99
_config.version.yml
10+
11+
# Generated or copied from other repo resources
12+
_includes/components/generated/*

‎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-includes
2323
npm run build $(baseurlparam)
2424

25-
debug: version
25+
debug: version .generate-includes
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-includes:
43+
npm run generate-includes

‎docs/_config.yml‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,19 +18,49 @@
1818
# You can create any custom variable you would like, and they will be accessible
1919
# in the templates via {{ site.myvariable }}.
2020

21-
title: NHS Notify Repo Template
21+
title: NHS Notify Supplier API
2222
# email: [email protected]
2323
description: >- # this means to ignore newlines until "baseurl:"
24-
Repository Template documentation for the NHS Notify Platform.
24+
Documentation for the NHS Notify Supplier API
2525
baseurl: "" # the subpath of your site, e.g. /blog
2626
url: "https://nhsdigital.github.io" # the base hostname & protocol for your site, e.g. http://example.com
2727

2828
collections_dir: collections
2929

3030
collections:
31-
notify-repos:
31+
consumers:
3232
output: true
3333
sort_by: order
34+
developers:
35+
output: true
36+
sort_by: order
37+
38+
just_the_docs:
39+
collections:
40+
consumers:
41+
name: API Consumers
42+
developers:
43+
name: API Developers
44+
45+
defaults:
46+
- scope:
47+
path: ""
48+
type: "consumers"
49+
values:
50+
layout: "page"
51+
is_not_draft: false
52+
owner: NHS Notify
53+
author: NHS Notify
54+
last_modified_date: 2025-10-08
55+
- scope:
56+
path: ""
57+
type: "developers"
58+
values:
59+
layout: "page"
60+
is_not_draft: false
61+
owner: NHS Notify
62+
author: NHS Notify
63+
last_modified_date: 2025-10-08
3464

3565
# Build settings
3666
theme: just-the-docs
@@ -45,15 +75,15 @@ mermaid:
4575
version: "10.9.1"
4676

4777
aux_links:
48-
"NHS Notify Repo Template on GitHub":
49-
- "//github.com/NHSDigital/nhs-notify-repository-template"
78+
"NHS Notify Supplier API Template on GitHub":
79+
- "//github.com/NHSDigital/nhs-notify-supplier-api"
5080

5181
aux_links_new_tab: false
5282

5383
# Footer "Edit this page on GitHub" link text
5484
gh_edit_link: true # show or hide edit this page link
5585
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
86+
gh_edit_repository: "https://github.com/NHSDigital/nhs-notify-supplier-api" # the github URL for your repo
5787
gh_edit_branch: "main" # the branch that your docs is served from
5888
# gh_edit_source: docs # the source that your files originate from
5989
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 }}

0 commit comments

Comments
 (0)