From b86c67c720304d55c105422ac410d247940e562a Mon Sep 17 00:00:00 2001 From: Marco Ferrari Date: Sat, 19 Oct 2024 20:04:38 +0200 Subject: [PATCH] docs: generate a website with mkdocs --- .github/workflows/documentation.yaml | 35 ++++++++++++++ README.md | 22 ++------- config/lint/.jscpd.json | 1 + config/lint/super-linter.env | 1 + config/mkdocs/home-lab-docs/mkdocs.yaml | 13 +++++ config/pre-commit/.pre-commit-config.yaml | 2 +- docs/README.md | 19 ++++++++ docs/architecture/README.md | 9 +--- scripts/build-arduino-project.sh | 3 +- scripts/common.sh | 3 ++ scripts/run-ansible.sh | 6 +-- scripts/run-mkdocs.sh | 58 +++++++++++++++++++++++ 12 files changed, 140 insertions(+), 32 deletions(-) create mode 100644 .github/workflows/documentation.yaml create mode 100644 config/mkdocs/home-lab-docs/mkdocs.yaml create mode 100644 docs/README.md create mode 100755 scripts/run-mkdocs.sh diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 000000000..82466cb4f --- /dev/null +++ b/.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" diff --git a/README.md b/README.md index 79b3c317d..a7a07d36b 100644 --- a/README.md +++ b/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). diff --git a/config/lint/.jscpd.json b/config/lint/.jscpd.json index 720136a8a..c140d899c 100644 --- a/config/lint/.jscpd.json +++ b/config/lint/.jscpd.json @@ -5,6 +5,7 @@ "**/.esphome/**", "**/.venv*/**", "**/grafana/dashboards/dashboard-definitions/**/*.json", + "**/site/**", "**/user-data*.yaml" ], "absolute": true, diff --git a/config/lint/super-linter.env b/config/lint/super-linter.env index 6ebfb1be9..c9da7f468 100644 --- a/config/lint/super-linter.env +++ b/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 diff --git a/config/mkdocs/home-lab-docs/mkdocs.yaml b/config/mkdocs/home-lab-docs/mkdocs.yaml new file mode 100644 index 000000000..c6be5cae0 --- /dev/null +++ b/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 diff --git a/config/pre-commit/.pre-commit-config.yaml b/config/pre-commit/.pre-commit-config.yaml index 6a541074c..8f88a7aa7 100644 --- a/config/pre-commit/.pre-commit-config.yaml +++ b/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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..2ee1e7cb3 --- /dev/null +++ b/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). diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 403048bda..4bd4010a9 100644 --- a/docs/architecture/README.md +++ b/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) diff --git a/scripts/build-arduino-project.sh b/scripts/build-arduino-project.sh index 3a6aec4fc..ab1493b48 100755 --- a/scripts/build-arduino-project.sh +++ b/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 diff --git a/scripts/common.sh b/scripts/common.sh index 4ad974006..64d4dea33 100755 --- a/scripts/common.sh +++ b/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" diff --git a/scripts/run-ansible.sh b/scripts/run-ansible.sh index a40ef20e7..df36f817b 100755 --- a/scripts/run-ansible.sh +++ b/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 diff --git a/scripts/run-mkdocs.sh b/scripts/run-mkdocs.sh new file mode 100755 index 000000000..004e79aa8 --- /dev/null +++ b/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[@]}"