Mkdocs material documentation

.env

@@ -1,62 +1,62 @@
 COMPOSE_PROJECT_NAME=ocrd_kitodo
 
 # Manager SSH server
-MANAGER_IMAGE=ghcr.io/slub/ocrd_manager:latest
-MANAGER_HOST=ocrd-manager
-MANAGER_PORT_SSH=9022
-MANAGER_ENV_UID=1001
-MANAGER_ENV_GID=1001
-MANAGER_ENV_UMASK=0002
-MANAGER_KEYS=${PWD}/ocrd/manager/.ssh/authorized_keys
-MANAGER_KEY=${PWD}/ocrd/manager/.ssh/id_rsa
-MANAGER_DATA=${PWD}/kitodo/data/metadata
+MANAGER_IMAGE=ghcr.io/slub/ocrd_manager:latest # name and tag of image
+MANAGER_HOST=ocrd-manager # name/address of server (for Kitodo)
+MANAGER_PORT_SSH=9022 # host-side port to exposed SSH server (for external Kitodo)
+MANAGER_ENV_UID=1001 # user id of SSH user (`id -u` when using `make`)
+MANAGER_ENV_GID=1001 # group id of SSH user (`id -g` when using `make`)
+MANAGER_ENV_UMASK=0002 # ssh user specific permission mask
+MANAGER_KEYS=${PWD}/ocrd/manager/.ssh/authorized_keys # file path with public SSH keys of users allowed to log in
+MANAGER_KEY=${PWD}/ocrd/manager/.ssh/id_rsa # file path with private SSH key of internal `ocrd` user (should match one of `CONTROLLER_KEYS`)
+MANAGER_DATA=${PWD}/kitodo/data/metadata # persistent data volume to mount
 
 # Monitor Web server
-MONITOR_IMAGE=ghcr.io/slub/ocrd_monitor:latest
-MONITOR_HOST=ocrd-monitor
-MONITOR_PORT_WEB=5000
-MONITOR_PORT_GTK=8500
-MONITOR_PORT_LOG=8088
-MONITOR_DATA=${PWD}/kitodo/data/metadata
+MONITOR_IMAGE=ghcr.io/slub/ocrd_monitor:latest # name and tag of image
+MONITOR_HOST=ocrd-monitor # name/address of server
+MONITOR_PORT_WEB=5000 # host-side port to exposed Web server
+MONITOR_PORT_GTK=8500 # host-side port to exposed Broadwayd (Gtk Web server)
+MONITOR_PORT_LOG=8088 # host-side port to exposed Dozzle (Docker log viewer)
+MONITOR_DATA=${PWD}/kitodo/data/metadata # persistent data volume to mount
 
 # Controller SSH server (with-ocrd-controller)
-CONTROLLER_IMAGE=ghcr.io/slub/ocrd_controller:latest
-CONTROLLER_HOST=ocrd-controller
-CONTROLLER_PORT_SSH=22
-CONTROLLER_ENV_UID=1001
-CONTROLLER_ENV_GID=1001
-CONTROLLER_ENV_UMASK=0002
-CONTROLLER_KEYS=${PWD}/ocrd/controller/.ssh/authorized_keys
-CONTROLLER_DATA=${PWD}/kitodo/data/metadata
-CONTROLLER_MODELS=${PWD}/ocrd/controller/models
-CONTROLLER_CONFIG=${PWD}/ocrd/controller/config
-CONTROLLER_WORKERS=1
+CONTROLLER_IMAGE=ghcr.io/slub/ocrd_controller:latest # name and tag of image
+CONTROLLER_HOST=ocrd-controller # name/address of server (for Manager/Monitor)
+CONTROLLER_PORT_SSH=22 # SSH port (for Manager/Monitor)
+CONTROLLER_ENV_UID=1001 # user id of SSH user (`id -u` when using `make`)
+CONTROLLER_ENV_GID=1001 # group id of SSH user (`id -g` when using `make`)
+CONTROLLER_ENV_UMASK=0002 # SSH user specific permission mask
+CONTROLLER_KEYS=${PWD}/ocrd/controller/.ssh/authorized_keys # file path with public SSH keys of users allowed to log in
+CONTROLLER_DATA=${PWD}/kitodo/data/metadata # persistent data volume to mount
+CONTROLLER_MODELS=${PWD}/ocrd/controller/models # path to persistent models (in `ocrd-resources/`)
+CONTROLLER_CONFIG=${PWD}/ocrd/controller/config # path to persistent config (in `ocrd/resources.yml`)
+CONTROLLER_WORKERS=1 # number of workers for processing
 
 # Application Kitodo.Production (with-kitodo-production)
-APP_IMAGE=ghcr.io/slub/ocrd_kitodo/kitodo_production_ocrd:latest
-APP_BUILD_CONTEXT=${PWD}/_modules/kitodo-production-docker/
-APP_BUILDER_GIT_COMMIT=ocrd-main
-APP_BUILDER_GIT_SOURCE_URL=https://github.com/markusweigelt/kitodo-production/
-APP_DATA=${PWD}/kitodo/data
-APP_KEY=${PWD}/kitodo/.ssh/id_rsa
-APP_PORT=8080
+APP_IMAGE=ghcr.io/slub/ocrd_kitodo/kitodo_production_ocrd:latest # name and tag of image
+APP_BUILD_CONTEXT=${PWD}/_modules/kitodo-production-docker/ # directory of Dockerfile
+APP_BUILDER_GIT_COMMIT=ocrd-main # branch "ocrd-main" of git repository (cause using `git` as `BUILDER_TYPE`)
+APP_BUILDER_GIT_SOURCE_URL=https://github.com/markusweigelt/kitodo-production/ # repository of `BUILDER_GIT_COMMIT` (cause using `git` as `BUILDER_TYPE`)
+APP_DATA=${PWD}/kitodo/data # persistent volume of application data to mount, e.g. config and modules
+APP_KEY=${PWD}/kitodo/.ssh/id_rsa # file path with private SSH key of `ocrd` user (should match one of `MANAGER_KEYS`)
+APP_PORT=8080 # host-side port of Kitodo.Production
 
 # Database (with-kitodo-production)
-DB_IMAGE=mysql:8.0.31
-DB_HOST=kitodo-db
-DB_PORT=3306
-DB_ROOT_PASSWORD=1234
-DB_NAME=kitodo
-DB_USER=kitodo
-DB_USER_PASSWORD=kitodo
+DB_IMAGE=mysql:8.0.31 # name and tag of image
+DB_HOST=kitodo-db # name/address of database (for Kitodo)
+DB_PORT=3306 # host-side port to exposed database
+DB_ROOT_PASSWORD=1234 # root user password
+DB_NAME=kitodo # name of database used by Kitodo.Production
+DB_USER=kitodo # username to access database
+DB_USER_PASSWORD=kitodo # password used by username to access database
 
 # Elastic Search (with-kitodo-production)
-ES_IMAGE=elasticsearch:7.17.7
-ES_HOST=kitodo-es
-ES_REST_PORT=9200
-ES_NODE_PORT=9300
+ES_IMAGE=elasticsearch:7.17.7 # name and tag of image
+ES_HOST=kitodo-es # name/address of server (for Kitodo)
+ES_REST_PORT=9200 # host-side port to REST API
+ES_NODE_PORT=9300 # host-side port to inter-node protocol
 
 # Active MQ (with-kitodo-production)
-MQ_IMAGE=markusweigelt/activemq:latest
-MQ_HOST=kitodo-mq
-MQ_PORT=61616
+MQ_IMAGE=markusweigelt/activemq:latest # name and tag of image
+MQ_HOST=kitodo-mq # name/address of server (for Kitodo/Manager)
+MQ_PORT=61616 # host-side port to exposed TCP Transport

.github/scripts/build-env-mds.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+LASTPREFIX=""
+TARGETDIR="./docs/_generated/"
+mkdir -p $TARGETDIR
+grep -v '^\s*$\|^\s*\#' .env | while read -r line; do
+	PREFIX=${line%%_*}
+	if [ "$PREFIX" == "COMPOSE" ]; then
+		continue
+	fi
+	FILENAME=${TARGETDIR}env-${PREFIX,,}-table.md 
+	if [ "$PREFIX" != "$LASTPREFIX" ]; then
+		echo '| Name | Default | Description' >> $FILENAME
+		echo '| --- | --- | ---' >> $FILENAME
+	fi
+	echo $line | sed 's/ / | /; s/=/ | /; s/| #/| /; s/^/| /; s/${PWD}/./' | sed -r -e 's/\.\/([^ ]*)/`\.\/\1`/;'   >> $FILENAME
+	LASTPREFIX=$PREFIX
+done

.github/workflows/publish-documentation.yml

@@ -0,0 +1,26 @@
+name: Publish the documentation of integration of OCR-D and Kitodo
+on:
+  push:
+    branches:
+      - main
+      - mkdocs-material
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository and submodules
+        uses: actions/checkout@v2
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Build environment variable markdown files
+        run: ./.github/scripts/build-env-mds.sh
+        shell: bash
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-monorepo-plugin
+      - run: pip install mkdocs-macros-plugin
+      - run: pip install mkdocs-exclude-search
+      - run: mkdocs build --theme material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -3,3 +3,5 @@
 *.iml
 /docker-compose.kitodo-app.dev.yml
 /.idea/*
+_generated
+site