feat(docs): Improve documentation and enforce markdown linting

.githooks/README.md

@@ -8,6 +8,6 @@ In this directory is a collection of helpful git hooks to ease your development
 
 Setup is easy, just configure git to use this as your hooks path instead of the default:
 
-```sh
+```bash
 git config core.hooksPath .githooks
 ```

.github/actions/README.md

@@ -1,35 +1,35 @@
 # GitHub Actions supporting scripts
 
 In this section of the repo you will find GitHub specific integrations. We really hope there will not be many of them.
 
 ## Testing
 
 ```
 yarn
 yarn test
 ```
 
 ## Building/Packaging
 
 ```
 yarn
 yarn build
 ```
 
 ## Running locally
 
 Running locally can be done by using [local-runner.ts](./local-runner.ts). You will need a GitHub PAT with `repo`
 permissions.
 
-```shell
+```bash
 node -r esbuild-runner/register local-runner.ts
 ```
 
 # Change detection script
 
 ## What is a Github PR?
 
 Basically a PR is a sort of "dry-run" of what would happen if you merged your branch to the base branch at a given point
 in time. Here is what roughly happens when you open a PR:
 
 ```mermaid
@@ -49,14 +49,14 @@
     classDef merge fill:orange;
 ```
 
 If the two branches cannot be merged together, someone must step in to fix that up. If the two branches can be merged
 together, then that's great and at least it means the head branch can be auto-merged into the base one. If there are
 GitHub Actions workflows configured for this event (pull request, that is) and the `PR1` merge was successful, then
 those are executed.
 
 ## The challenge
 
 In the context of monorepo, such as we are, re-building and re-integrating the code at every step fully is very
 expensive (and only getting more so over time) in all kinds of ways and is therefore impractical. We are employing a
 process where we re-integrate and re-build only the components that have changed from the last successful build.
 

.github/workflows/pullrequest.yml

@@ -333,6 +333,27 @@ jobs:
           ./scripts/ci/20_check-formatting.sh "write"
           ./infra/scripts/ci/git-check-dirty.sh "/" "nx format:write" "dirtybot"
 
+  docs:
+    needs:
+      - prepare
+    runs-on: ec2-runners
+    container:
+      image: public.ecr.aws/m3u4c4h9/island-is/actions-runner-public:latest
+    if: needs.prepare.outputs.LINT_CHUNKS
+    # env:
+    #   AFFECTED_PROJECTS: ${{ matrix.projects }}
+    #   NODE_OPTIONS: --max-old-space-size=4096
+    #   MAX_JOBS: 3
+    # strategy:
+    #   fail-fast: false
+    #   matrix: ${{ fromJson(needs.prepare.outputs.LINT_CHUNKS) }}
+    steps:
+      - name: Markdown linting
+        uses: DavidAnson/markdownlint-cli2-action@v17
+        with:
+          globs: |
+            **/*.md
+
   linting:
     needs:
       - prepare
@@ -362,7 +383,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           keys: ${{ needs.prepare.outputs.CACHE_KEYS }}
           enable-cache: 'node_modules,generated-files'
-      - name: Linting
+      - name: Nx linting
         run: ./scripts/ci/run-in-parallel-native.sh lint
 
   build:

.markdownlint.yaml

@@ -0,0 +1,7 @@
+# Default state for all rules
+default: true
+
+# MD013/line-length - Line length
+MD013:
+  line_length: 1000
+  tables: false

apps/air-discount-scheme/README.md

@@ -2,13 +2,9 @@
 
 ## About
 
-Generates discount codes that can be used for booking domestic flights online.
+Generates discount codes for eligible domestic flight bookings. Eligibility:
 
-There are certain precondition to be eligible for a discount. They are:
-
-- The person's legal domicile needs to be in a predefined set of towns outside
-  the capital (We fetch postal codes from Þjóðskrá to validate if user is
-  eligible).
+- Legal domicile in specified towns outside the capital. Validated using Þjóðskrá postal codes.
 
 ## URLs
 
@@ -18,13 +14,7 @@ There are certain precondition to be eligible for a discount. They are:
 
 ## API
 
-The API is used by airlines to verify the discount code validity and get basic
-booking info about the user.
-
-The airlines that have access to this api are `Icelandair`, `Ernir` and
-`Norlandair`. Historically some flights were booked for `Norlandair` through
-`Icelandair`, those flights are marked with the `Icelandair` airline but have a
-cooperation field with `Norlandair`.
+Airlines can verify discount codes and access basic booking info. Authorized airlines: `Icelandair`, `Ernir`, `Norlandair`. Flights booked through `Icelandair` for `Norlandair` are marked with `Icelandair`, with a cooperation field for `Norlandair`.
 
 [Swagger API](https://loftbru.dev01.devland.is/api/swagger)
 
@@ -34,8 +24,7 @@ yarn start air-discount-scheme-api
 
 ## Backend
 
-The admin frontend has a view over the bookings that have been registered in
-the system. This is mainly for Vegagerðin.
+The admin interface offers an overview of registered bookings, mainly for Vegagerðin.
 
 [Admin](https://loftbru.dev01.devland.is/admin)
 
@@ -45,8 +34,7 @@ yarn start air-discount-scheme-backend
 
 ## Web
 
-The user frontend has information about the initiative, legal terms and a way
-for users to get their discount codes.
+Includes initiative details, legal terms, and a tool for obtaining discount codes.
 
 [Dev](https://loftbru.dev01.devland.is)
 
@@ -56,89 +44,73 @@ yarn start air-discount-scheme-web
 
 ## Integrations
 
-- [Þjóðskrá](https://skra.is): To be able to verify the persons legal domicile,
-  give the airlines basic information about the person and fetch a persons
-  relations to show the discount codes for related children.
+- [Þjóðskrá](https://skra.is): Validates legal domicile and provides airlines with personal info and discount codes for related children.
 
 ## Development
 
-To get started developing this project, go ahead and:
-
-1. Fetch the environment secrets:
-
-```bash
-yarn get-secrets air-discount-scheme-api
-yarn get-secrets air-discount-scheme-backend
-yarn get-secrets air-discount-scheme-web
-```
+To start development:
 
-2. Start the resources with docker compose and migrate/seed the database:
+1. Fetch environment secrets:
 
-```bash
-docker compose -f apps/air-discount-scheme/backend/docker-compose.yml up
-```
+   ```bash
+   yarn get-secrets air-discount-scheme-api
+   yarn get-secrets air-discount-scheme-backend
+   yarn get-secrets air-discount-scheme-web
+   ```
 
-```bash
-yarn nx run air-discount-scheme-backend:migrate
+2. Start resources with Docker Compose and migrate/seed the database:
 
-yarn nx run air-discount-scheme-backend:seed
-```
+   ```bash
+   docker compose -f apps/air-discount-scheme/backend/docker-compose.yml up
+   yarn nx run air-discount-scheme-backend:migrate
+   yarn nx run air-discount-scheme-backend:seed
+   ```
 
 3. Start the front end:
 
-```bash
-yarn start air-discount-scheme-web
-```
+   ```bash
+   yarn start air-discount-scheme-web
+   ```
 
-4. Start the graphql api:
+4. Start the GraphQL API:
 
-```bash
-yarn start air-discount-scheme-api
-```
+   ```bash
+   yarn start air-discount-scheme-api
+   ```
 
-5. Start the backend api:
+5. Start the backend API:
 
-```bash
-yarn start air-discount-scheme-backend
-```
+   ```bash
+   yarn start air-discount-scheme-backend
+   ```
 
-6. Check Contentful and AWS
+6. Verify Contentful and AWS:
 
-Login here <https://island-is.awsapps.com/start#/> (Contact devops if you need access)
-Copy env variables as instructed [here](https://docs.devland.is/technical-overview/devops/dockerizing#troubleshooting) (image arrows 1,2,3)
-Paste env variables into terminal
-Run `./scripts/run-es-proxy.sh` from island.is root
-You have success if you see `Forwarding from 0.0.0.0:9200 -> 9200` in terminal
+   Log in at <https://island-is.awsapps.com/start#/> (Contact devops for access). Copy environment variables as described in [the documentation](https://docs.devland.is/technical-overview/devops/dockerizing#troubleshooting), then paste into terminal. Execute `./scripts/run-es-proxy.sh` from island.is root directory. Success is indicated by `Forwarding from 0.0.0.0:9200 -> 9200`.
 
-Navigate to [localhost:4200](http://localhost:4200) for the website or
-[localhost:4248/api/swagger/](http://localhost:4248/api/swagger/) for the
-airline api.
+Visit [localhost:4200](http://localhost:4200) for the website or [localhost:4248/api/swagger/](http://localhost:4248/api/swagger/) for the airline API.
 
 ### Admin
 
-To access the Admin UI, you'll need to add your Icelandic National ID to the
-comma separated environment variable `DEVELOPERS` (.env.secret) and restart the
-`api`.
+To access the Admin UI, add your Icelandic National ID to the `DEVELOPERS` environment variable in `.env.secret` and restart the API.
 
 ```bash
 export DEVELOPERS=1234567890
 ```
 
 ## Shortcuts
 
-Because of the short timeline this assignment had, there were few shortcuts
-taken that can be improved upon:
+Due to time constraints, certain shortcuts were taken:
 
-- The authentication is pretty primitive, the IDP is still in development at
-  the time of this writing so we needed to use static api keys.
-- The deployment pipeline is outside of the islandis main pipeline.
-- The graphql api is separate of the main graphql api of islandis.
+- Basic authentication with static API keys; IDP was in development.
+- Separate deployment pipeline from the main island.is pipeline.
+- Independent GraphQL API from island.is's main API.
 
-## Project owner
+## Project Owner
 
 - [Vegagerðin](http://www.vegagerdin.is)
 
-## Code owners and maintainers
+## Code Owners and Maintainers
 
 - [Brian - @barabrian](https://github.com/barabrian)
 - [Davíð Guðni - @dabbeg](https://github.com/dabbeg)