docs: generate a website with mkdocs

.github/workflows/documentation.yaml

@@ -0,0 +1,45 @@
+---
+name: Build and publish documentation site
+
+on: # yamllint disable-line rule:truthy
+  push:
+    paths:
+      - ".github/workflows/documentation.yaml"
+      - "docs/**"
+      - "config/mkdocs/home-lab-docs/**"
+      - scripts/run-mkdocs.sh
+  pull_request:
+    paths:
+      - ".github/workflows/documentation.yaml"
+      - "docs/**"
+      - "config/mkdocs/home-lab-docs/**"
+      - scripts/run-mkdocs.sh
+  workflow_call: null
+
+permissions:
+  contents: read
+
+jobs:
+  build-documentation-site:
+    concurrency:
+      # Ref: https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
+      # github.head_ref: head_ref or source branch of the pull request
+      # github.ref: ref of the branch that triggered the workflow
+      group: ${{ github.workflow }}-build-documentation-sites-${{ github.head_ref || github.ref }}-${{ github.event_name }}
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the documentation site
+        run: |
+          scripts/run-mkdocs.sh "build"
+      - name: Commit and push updates to the documentation site
+        if: >
+          github.event_name == 'pull_request' &&
+          github.ref_name != github.event.repository.default_branch
+        uses: stefanzweifel/git-auto-commit-action@v5.0.1
+        with:
+          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
+          commit_message: "chore: update documentation site"
+          commit_user_name: github-actions[bot]
+          commit_user_email: 41898282+github-actions[bot]@users.noreply.g

README.md

@@ -1,19 +1,5 @@
-# ferrarimarco's Home Lab
+# My Home Lab
 
-All the necessary to provision, configure and manage my home lab.
-
-Before using the home lab, you initialize the environments by executing
-a manual process. After the initalization process completes,
-automated processes take care of applying provisioning and
-configuration changes to the environments.
-
-## Get started
-
-For more information about how to set up the lab, see:
-
-- [Initialize the home lab on physical hardware](./docs/installation/production/README.md).
-
-## Architecture
-
-For more information about the architecture of the lab, see
-[Architecture](./docs/architecture/README.md).
+For more information about how to set up the lab, see
+[the webesite](https://ferrarimarco.github.io/home-lab)
+or the contents of the [docs directory](./docs/README.md).

config/lint/.jscpd.json

@@ -5,6 +5,7 @@
     "**/.esphome/**",
     "**/.venv*/**",
     "**/grafana/dashboards/dashboard-definitions/**/*.json",
+    "**/site/**",
     "**/user-data*.yaml"
   ],
   "absolute": true,

config/lint/super-linter.env

@@ -1,5 +1,6 @@
 ANSIBLE_DIRECTORY=docker/ansible/etc/ansible
 CREATE_LOG_FILE=true
+FILTER_REGEX_EXCLUDE=^site/
 GITLEAKS_LOG_LEVEL=warn
 IGNORE_GITIGNORED_FILES=true
 LINTER_RULES_PATH=config/lint

config/mkdocs/home-lab-docs/mkdocs.yaml

@@ -0,0 +1,13 @@
+---
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+docs_dir: "../../../docs"
+repo_url: https://github.com/ferrarimarco/home-lab
+site_dir: "../../../site"
+site_name: Home Lab docs
+site_url: https://ferrarimarco.github.io/home-lab
+strict: true
+theme:
+  name: material
+  features:
+    - navigation.top
+    - navigation.tracking

config/pre-commit/.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 ---
+# yaml-language-server: $schema=https://json.schemastore.org/pre-commit-config.json
 exclude: |
   (?x)^(
       .*\.venv.*
@@ -27,7 +28,6 @@ repos:
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: fix-byte-order-marker
-      - id: fix-encoding-pragma
       - id: mixed-line-ending
       - id: requirements-txt-fixer
       - id: trailing-whitespace

docs/README.md

@@ -0,0 +1,19 @@
+# Home lab
+
+All the necessary to provision, configure and manage my home lab.
+
+Before using the home lab, you initialize the environments by executing
+a manual process. After the initalization process completes,
+automated processes take care of applying provisioning and
+configuration changes to the environments.
+
+## Get started
+
+For more information about how to set up the lab, see:
+
+- [Initialize the home lab on physical hardware](./installation/production/README.md).
+
+## Architecture
+
+For more information about the architecture of the lab, see
+[Architecture](./architecture/README.md).

docs/architecture/README.md

@@ -1,4 +1,4 @@
-# Architecture
+# Home lab architecture overview
 
 This document describes the architecture of the lab.
 
@@ -38,10 +38,5 @@ configuration, and deployment processes:
 - GitHub-specific configuration in the `.github` directory.
 - Configuration for each architectural layer and support tooling in the `config` directory.
 - Container image descriptors in the `docker` directory.
-- Documentation in the `docs` directory and in the [main readme](../../README.md).
+- Documentation in the `docs` directory.
 - Operational scripts in the `scripts` directory.
-
-## Further reading
-
-- [DNS zones, servers, and resolvers](./dns-zones-servers-resolvers.md)
-- [References](./references.md)

scripts/build-arduino-project.sh

@@ -37,8 +37,7 @@ if [ -n "${ARDUINO_BOARD_PORT}" ]; then
   if [ ! -e "${ARDUINO_BOARD_PORT}" ]; then
     echo "[ERROR] ${ARDUINO_BOARD_PORT} is not available."
     # Ignoring because those are defined in common.sh, and don't need quotes
-    # shellcheck disable=SC2086
-    exit ${ERR_ARGUMENT_EVAL}
+    exit "${ERR_ARGUMENT_EVAL}"
   fi
 
   if [ "${ARDUINO_UPLOAD:-"true"}" = "true" ]; then

scripts/common.sh

@@ -15,6 +15,9 @@ CD_CONTAINER_URL="ferrarimarco/home-lab-cd:latest"
 
 GITHUB_TOKEN_PATH="$(pwd)/.github-personal-access-token"
 
+# shellcheck disable=SC2034
+HOME_LAB_DOCS_CONFIGURATION_FILE_PATH="config/mkdocs/home-lab-docs/mkdocs.yml"
+
 _DOCKER_INTERACTIVE_TTY_OPTION=
 if [ -t 0 ]; then
   _DOCKER_INTERACTIVE_TTY_OPTION="-it"

scripts/run-ansible.sh

@@ -65,8 +65,7 @@ if [ -n "${ANSIBLE_TEST_DISTRO:-}" ]; then
   ANSIBLE_TEST_PLAYBOOK_FULL_PATH="config/ansible/molecule/default/${ANSIBLE_TEST_PLAYBOOK_PATH}"
   if [ ! -f "${ANSIBLE_TEST_PLAYBOOK_FULL_PATH}" ]; then
     echo "The playbook file does not exist: ${ANSIBLE_TEST_PLAYBOOK_FULL_PATH}"
-    # shellcheck disable=SC2086
-    exit ${ERR_ANSIBLE_TEST_MISSING_PLAYBOOK}
+    exit "${ERR_ANSIBLE_TEST_MISSING_PLAYBOOK}"
   fi
 
   COMMAND_TO_RUN="${COMMAND_TO_RUN} --env ANSIBLE_TEST_DISTRO=${ANSIBLE_TEST_DISTRO}"
@@ -86,8 +85,7 @@ else
 
   if [ ! -f "${ANSIBLE_VAULT_PASSWORD_FILE_PATH}" ]; then
     echo "The Ansible vault password file does not exist: ${ANSIBLE_VAULT_PASSWORD_FILE_PATH}"
-    # shellcheck disable=SC2086
-    exit ${ERR_ANSIBLE_MISSING_PASSWORD_FILE}
+    exit "${ERR_ANSIBLE_MISSING_PASSWORD_FILE}"
   fi
 fi
 

scripts/run-mkdocs.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# shellcheck source=/dev/null
+. "./scripts/common.sh"
+
+# renovate: datasource=docker packageName=squidfunk/mkdocs-material versioning=docker
+MKDOCS_CONTAINER_IMAGE_VERSION="9.5.41"
+MKDOCS_CONTAINER_IMAGE="squidfunk/mkdocs-material:${MKDOCS_CONTAINER_IMAGE_VERSION}"
+
+echo "Running mkdocs: ${MKDOCS_CONTAINER_IMAGE}"
+
+SUBCOMMAND="${1}"
+echo "Subcommand: ${SUBCOMMAND}"
+
+RUN_CONTAINER_COMMAND=(
+  docker run
+  --rm
+)
+
+if [ -t 0 ]; then
+  RUN_CONTAINER_COMMAND+=(
+    --interactive
+    --tty
+  )
+fi
+
+RUN_CONTAINER_COMMAND+=(
+  --name "mkdocs"
+  --publish "8000:8000"
+  --volume "$(pwd)":/docs
+  --volume /etc/localtime:/etc/localtime:ro
+  "${MKDOCS_CONTAINER_IMAGE}"
+)
+
+DEFAULT_MKDOCS_ARGS=(
+  --config-file config/mkdocs/home-lab-docs/mkdocs.yaml
+)
+
+if [[ "${1}" == "serve" ]]; then
+  RUN_CONTAINER_COMMAND+=(
+    "serve"
+    "--dev-addr=0.0.0.0:8000"
+    "${DEFAULT_MKDOCS_ARGS[@]}"
+  )
+elif [[ "${1}" == "build" ]]; then
+  RUN_CONTAINER_COMMAND+=(
+    "build"
+    "${DEFAULT_MKDOCS_ARGS[@]}"
+  )
+elif [[ "${1}" == "create" ]]; then
+  RUN_CONTAINER_COMMAND+=(
+    "new"
+    .
+  )
+fi
+
+echo "Run container command: ${RUN_CONTAINER_COMMAND[*]}"
+"${RUN_CONTAINER_COMMAND[@]}"