docs: generate a website with mkdocs

.github/workflows/documentation.yaml

@@ -0,0 +1,35 @@
+---
+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"

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[@]}"