Improve core documentation

.github/workflows/publish-documentation.yml

@@ -1,6 +1,9 @@
 name: Publish documentation
 
-on: push
+on:
+  push:
+    branches:
+      - main
 
 # GITHUB_TOKEN permissions to allow deployment to GitHub Pages
 permissions:

.trufflehog3.yml

@@ -7,6 +7,8 @@ exclude: # exclude matching issues
       - .github/**
       - .ruff_cache/**
       - .pytest_cache/**
+      - .venv/**
+      - .idea/**
   - message: Examples and data necessary for running auto-tests
     paths:
       - docs/*.html

docs/source/documentation/access.html.md.erb

@@ -0,0 +1,29 @@
+## Access
+
+To use the API you will need a JSON Web Token (JWT) which can be obtained from the `/token` endpoint.
+
+You will need to send a `POST` request with the following headers:
+
+```json
+{
+    "accept": "application/json",
+    "Content-Type": "application/x-www-form-urlencoded"
+}
+```
+
+and body:
+
+```json
+ {
+    "grant_type": "password",
+    "username": "string",
+    "password": "string",
+    "scope": "",
+    "client_id": "string",
+    "client_secret": "string"
+  }
+```
+
+The `/token` endpoint generates the required access token to allow a user to access the service. When submitting other requests, the request needs to contain this authorisation bearer token.
+
+All access tokens are valid for 30 minutes on the API.

docs/source/documentation/authentication.html.md.erb

@@ -1,4 +1,4 @@
-# Access Tokens
+## Access Tokens
 The /token endpoint generates the required access token to allow a user to access the service. When submitting other requests, the request needs to contain this authorisation bearer token.
 
 All access tokens are valid for 30 minutes on the API. This can be adjusted by amending ACCESS_TOKEN_EXPIRE_MINUTES on the auth/security.py file. This can be authenticated via a username and password which is compared to the hashed password in the database. As long as the user is logged in, a JWT token can be generated for their user.

docs/source/documentation/index.html.md.erb

@@ -2,43 +2,27 @@
 
 # LAA Civil Applications Data Store
 
-This is planned to be the central store of applications for Civil Legal Aid from [Check if you can get Legal Aid](https://checklegalaid.service.gov.uk/) and [Check if your client qualifies for legal aid](https://check-your-client-qualifies-for-legal-aid.service.gov.uk/).
+**This API and documentation are in early development.**
 
+This is planned to the be central store of eligibility checks from [Check if your client qualifies for legal aid](https://check-your-client-qualifies-for-legal-aid.service.gov.uk/) and civil legal advice cases from the [Civil Legal Advice](https://www.gov.uk/check-legal-aid) call centre.
 
-## API Documentation
+This API exists as a datastore allowing these resources to be stored and updated by the above services.
 
-Base URL:
+In the future this will allow these resources to be accessed throughout the users legal aid journey, reducing the need for users to re-answer questions and re-entry of data.
 
-```
-www.civil-case-api.cloud-platform.service.justice.gov.uk/
-```
+## Responsibilities of this API
+This API is responsible for storing and updating records, and for the data governance of these records.
 
-### Authentication
+This includes:
 
-To use the API you will need a JSON Web Token (JWT) which can be obtained from the `/token` endpoint.
+- Data security
+- Data integrity
+- Implementing data retention policies
 
-You will need to send a `POST` request with the following headers:
+This API is not responsible for the validity of the data, this is the responsibility of API users.
 
-```json
-{
-    "accept": "application/json",
-    "Content-Type": "application/x-www-form-urlencoded"
-}
-```
 
-and body:
+## Data structure
+The following is the current data structure for resources accessible in the API.
 
-```json
- {
-    "grant_type": "password",
-    "username": "string",
-    "password": "string",
-    "scope": "",
-    "client_id": "string",
-    "client_secret": "string"
-  }
-```
-
-The `/token` endpoint generates the required access token to allow a user to access the service. When submitting other requests, the request needs to contain this authorisation bearer token.
-
-All access tokens are valid for 30 minutes on the API.
+![Entity Relationship Diagram](../images/civil_case_data_erd.png)

docs/source/documentation/support.html.md.erb

@@ -0,0 +1,9 @@
+---
+title: Support
+---
+
+## Support
+
+This API is maintained by the Civil Legal Advice team.
+
+If you require support please reach out to `#laa-cla-dev`

docs/source/documentation/test_environments.html.md.erb

@@ -0,0 +1,13 @@
+---
+title: Test Environments
+---
+
+## Test Environments
+
+We plan on supporting the following test environment, with endpoints which will mirror production.
+
+```
+www.staging.civil-case-api.cloud-platform.service.justice.gov.uk/
+```
+
+To integrate with this environment you will require test credentials.

docs/source/index.html.md.erb

@@ -4,5 +4,6 @@ title: LAA Civil Applications Data Store
 
 <!-- This means open the file documentation/index.html as the entry point -->
 <%= partial 'documentation/index' %>
-<%= partial 'documentation/authentication' %>
+<%= partial 'documentation/support' %>
+<%= partial 'documentation/access' %>
 <%= partial 'documentation/case' %>