Lint docs using markdownlint-cli via pre-commit

.editorconfig

@@ -13,6 +13,6 @@ indent_size = 2
 indent_style = space
 indent_size = 2
 
-[{.golang-ci.yml,.markdownlint.json, docker-compose.yml, enduro.toml}]
+[{.golang-ci.yml,.markdownlint.jsonc, docker-compose.yml, enduro.toml}]
 indent_style = space
 indent_size = 2

.github/workflows/pre-commit.yml

@@ -0,0 +1,14 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v4
+    - uses: pre-commit/[email protected]

.github/workflows/workflowcheck.yml

@@ -21,4 +21,3 @@ jobs:
         run: go install go.temporal.io/sdk/contrib/tools/workflowcheck@latest
       - name: Run workflowcheck
         run: workflowcheck ./...
-

.markdownlint.jsonc

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD010": {
+    "code_blocks": false
+  },
+  "MD013": {
+    "code_blocks": false
+  },
+}

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+  - id: end-of-file-fixer
+    exclude: |
+      (?x)^(
+        dashboard/src/openapi-generator|
+        internal/api/gen
+      )
+- repo: https://github.com/igorshubovych/markdownlint-cli
+  rev: v0.37.0
+  hooks:
+  - id: markdownlint
+    files: 'docs/.*(?<!\.rst)$'

docs/requirements.in

@@ -1,3 +1,4 @@
 mkdocs
 mkdocs-autorefs
 mkdocs-literate-nav
+pre-commit

docs/requirements.txt

@@ -4,10 +4,18 @@
 #
 #    pip-compile
 #
+cfgv==3.4.0
+    # via pre-commit
 click==8.1.7
     # via mkdocs
+distlib==0.3.7
+    # via virtualenv
+filelock==3.13.1
+    # via virtualenv
 ghp-import==2.1.0
     # via mkdocs
+identify==2.5.31
+    # via pre-commit
 jinja2==3.1.2
     # via mkdocs
 markdown==3.5.1
@@ -29,21 +37,33 @@ mkdocs-autorefs==0.5.0
     # via -r requirements.in
 mkdocs-literate-nav==0.6.1
     # via -r requirements.in
+nodeenv==1.8.0
+    # via pre-commit
 packaging==23.2
     # via mkdocs
 pathspec==0.11.2
     # via mkdocs
 platformdirs==3.11.0
-    # via mkdocs
+    # via
+    #   mkdocs
+    #   virtualenv
+pre-commit==3.5.0
+    # via -r requirements.in
 python-dateutil==2.8.2
     # via ghp-import
 pyyaml==6.0.1
     # via
     #   mkdocs
+    #   pre-commit
     #   pyyaml-env-tag
 pyyaml-env-tag==0.1
     # via mkdocs
 six==1.16.0
     # via python-dateutil
+virtualenv==20.24.6
+    # via pre-commit
 watchdog==3.0.0
     # via mkdocs
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

docs/src/dev-manual/README.md

@@ -2,6 +2,7 @@
 
 This is the developer manual for Enduro SDPS.
 
+- [Documentation](docs.md)
 - [Dependency management](deps.md)
 - [Enviornment setup](devel.md)
 - [Logging](logging.md)

docs/src/dev-manual/devel.md

@@ -1,9 +1,9 @@
-## Local/Development environment
+# Local/Development environment
 
 Enduro uses Tilt to set up a local environment building the Docker images in a
 Kubernetes cluster. It has been tested with k3d, Minikube and Kind.
 
-### Requirements
+## Requirements
 
 - [Docker] (v18.09+)
 - [kubectl]
@@ -24,18 +24,19 @@ so that you don’t have to run Tilt with `sudo`. *Note that managing Docker as
 non-root user is **different** from running the docker daemon as a non-root user
 (rootless).*
 
-#### Dex host
+### Dex host
 
 To make authentication work from the host browser and from within the cluster,
 the following entry needs to be added to your `/etc/hosts` file:
 
-```
+```text
 127.0.0.1 dex
 ```
+
 For Windows/WSL2 users, open Notepad, as an Administrator, and then add the above
 to your `etc/hosts` file located like `C:/Windows/System32/drivers/etc/hosts`.
 
-### Requirements for development
+## Requirements for development
 
 While we run the services inside a Kubernetes cluster we recomend to install
 Go, Node and other tools locally to ease the development process.
@@ -46,7 +47,7 @@ Go, Node and other tools locally to ease the development process.
 
 If using Linux, Node.js binary distributions are available from [NodeSource].
 
-### Editor
+## Editor
 
 As source-code editor, we strongly recommended [Visual Studio Code] for its
 great out-of-the-box support for Go and TypeScript. The project includes some
@@ -59,51 +60,51 @@ extensions:
 - Prettier - Code formatter
 - ESLint
 
-### Set up
+## Set up
 
 Start a local Kubernetes cluster with a local registry. For example, with k3d:
 
-```
+```bash
 k3d cluster create sdps-local --registry-create sdps-registry
 ```
 
 Make sure kubectl is available and configured to use that cluster:
 
-```
+```bash
 kubectl config view
 ```
 
 Clone this repository and move into its folder if you have not done that
 previously:
 
-```
+```bash
 git clone [email protected]:artefactual-sdps/enduro.git
 cd enduro
 ```
 
 Bring up the environment:
 
-```
+```bash
 tilt up
 ```
 
 While the Docker images are built/downloaded and the Kubernetes resources are
 created, hit `space` to open the Tilt UI in your browser. Check the [Tilt UI]
 documentation to know more about it.
 
-### Access
+## Access
 
 There are four services available from the host:
 
-- Enduro dashboard: http://localhost:8080
-- Minio console: http://localhost:7460 (username: minio, password: minio123)
-- Temporal UI: http://localhost:7440
+- Enduro dashboard: <http://localhost:8080>
+- Minio console: <http://localhost:7460> (username: minio, password: minio123)
+- Temporal UI: <http://localhost:7440>
 
-### Live updates
+## Live updates
 
 Tilt, by default, will watch for file changes in the project folder and it will
 sync those changes, rebuild the Docker images and recreate the resources when
-necessary. However, we have *disabled* auto-load within the Tiltfile to reduce
+necessary. However, we have _disabled_ auto-load within the Tiltfile to reduce
 the use of hardware resources. There are refresh buttons on each resource in the
 Tilt UI that allow triggering manual updates and re-executing jobs and local
 resources. You can also set the `trigger_mode` env string to `TRIGGER_MODE_AUTO`
@@ -113,47 +114,48 @@ The `enduro-dashboard` uses Vite to serve the application in development
 with hot reload. The `enduro` and `enduro-a3m-worker` services require rebuilding
 the entire images - these will take longer to update.
 
-### Stop/start the environment
+## Stop/start the environment
 
 Run `ctrl-c` on the terminal where `tilt up` is running and stop the cluster
 with:
 
-```
+```bash
 k3d cluster stop sdps-local
 ```
 
 To start the environment again:
 
-```
+```bash
 k3d cluster start sdps-local
 tilt up
 ```
 
-### Clear the cluster
+## Clear the cluster
 
 > Check the Tilt UI helpers below to just flush the existing data.
 
 To remove the resources created by Tilt in the cluster, execute:
 
-```
+```bash
 tilt down
 ```
+
 Note that it will take some time to delete the persistent volumes when you
 run `tilt down` and flushing the existing data does not delete the cluster.
 To delete the volumes immediately, you can delete the cluster.
 
-### Delete the cluster
+## Delete the cluster
 
 Deleting the cluster will remove all the resources immediatly, deleting
 cluster container from the host. With k3d, run:
 
-```
+```bash
 k3d cluster delete sdps-local
 ```
 
-### Tilt UI helpers
+## Tilt UI helpers
 
-#### Upload to Minio
+### Upload to Minio
 
 In the Tilt UI header there is a cloud icon/button that allows you to configure
 and trigger an upload to the `sips` bucket in Minio. Click the caret to set the
@@ -169,19 +171,19 @@ sure you update `/path/to/enduro` to the proper project folder in the host):
 Alternatively, you can use the Enduro API to upload the file like in the
 following example:
 
-```
+```bash
 curl \
   -F "file=@/path/to/enduro/hack/sampledata/StructB-AM.zip" \
   http://localhost:9000/upload/upload
 ```
 
-#### Flush
+### Flush
 
 Also in the Tilt UI header, click the trash button to flush the existing data.
 This will recreate the MySQL databases and the MinIO buckets, and restart the
 required resources.
 
-#### Generators
+### Generators
 
 Grouped as tools, there are some code generators:
 
@@ -192,9 +194,9 @@ Grouped as tools, there are some code generators:
 This resources need to be triggered manually by default, but they can be
 configured to run automatically on code changes in the Tilt UI.
 
-### Known issues
+## Known issues
 
-#### Minio uploads don't trigger workflows
+### MinIO uploads don't trigger workflows
 
 The setup of the Minio buckets and the communication between Minio and Redis
 is sometimes not setup properly. To solve it, from the Tilt UI, restart the

docs/src/dev-manual/docs.md

@@ -0,0 +1,46 @@
+# Documentation
+
+These docs you are reading are built with MkDocs. This document describes the
+configuration of the local environment and the general writing workflow.
+
+## Environment configuration
+
+Clone the repository:
+
+    git clone https://github.com/artefactual-sdps/enduro
+
+Access the documentation directory:
+
+    cd enduro/docs
+
+Create a Python virtual environment if it has not been created yet:
+
+    python3 -m venv .venv
+
+Enable the virtual environment:
+
+    source .venv/bin/activate
+
+Install the dependencies:
+
+    pip install -r requirements.txt
+
+Optionally, synchronize the environment:
+
+    pip-sync
+
+## Writing workflow
+
+Run the builtin development server with live reloading support, which should
+be accessible under <http://127.0.0.1:8000/>.
+
+    mkdocs serve
+
+Run the following command to perform some basic linting before pushing your
+changes to GitHub:
+
+    pre-commit run --all-files
+
+The previous command uses `markdownlint-cli` to lint the docs using a library
+of [rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
+Please follow the link to troubleshoot any linting issues.

docs/src/dev-manual/logging.md

@@ -115,10 +115,10 @@ Don't use the [Temporal Go SDK logger] if possible.
 We want to avoid excessive error logging. As [Dave Cheney suggested], there are
 just two things that we should log:
 
-- _Things that users care about when using your software._<br />
+- _Things that users care about when using your software._\
   Mostly errors, using `logger.Error()`. Use `logger.Info()` very sparely.
 - _Things that developers care about when they are developing or debugging
-  software._<br/>
+  software._\
   Use V-Levels (gte 1), e.g.: `logger.V(1).Info()`.
 
 ## How do I choose my V-levels? (from the logr docs)

docs/src/dev-manual/make.md

@@ -11,7 +11,8 @@ Dependencies are downloaded automatically.
 
 `make gen-mock` generates mock interfaces with [mockgen](https://github.com/golang/mock).
 
-New mocks can be added to the project by adding a new `mockgen` line to `Makefile` that specifies the mock details (e.g. source, destination, package).
+New mocks can be added to the project by adding a new `mockgen` line to
+`Makefile` that specifies the mock details (e.g. source, destination, package).
 
 ## make lint