Merge pull request #25 from per1234/mkdocs

Add template workflows for managing a MkDocs-based website

Author: per1234

workflow-templates/assets/check-mkdocs-task/Taskfile.yml

@@ -0,0 +1,11 @@
+# See: https://taskfile.dev/#/usage
+version: "3"
+
+tasks:
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml
+  website:check:
+    desc: Check whether the MkDocs-based website will build
+    deps:
+      - task: poetry:install-deps
+    cmds:
+      - poetry run mkdocs build --strict

workflow-templates/assets/mkdocs/icon_mac_light.png

@@ -0,0 +1,47 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/mkdocs/mkdocs.yml
+# See: https://www.mkdocs.org/user-guide/configuration/
+
+# TODO: Fill in all blank fields below.
+site_name:
+site_description:
+site_url:
+
+repo_name:
+repo_url:
+edit_uri: blob/main/docs/
+
+copyright: Copyright 2021 ARDUINO SA (http://www.arduino.cc/)
+
+theme:
+  name: material
+  logo: img/icon_mac_light.png
+  palette:
+    primary: teal
+    accent: orange
+
+markdown_extensions:
+  - markdown.extensions.codehilite:
+      guess_lang: false
+  - markdown.extensions.toc:
+      permalink: true
+  - mdx_truly_sane_lists:
+      nested_indent: 2
+      truly_sane: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+      emoji_index: !!python/name:pymdownx.emoji.twemoji
+  - pymdownx.magiclink:
+      repo: contributor-guide
+      repo_url_shorthand: true
+      user: arduino
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+nav:
+  - Home: index.md
+  # TODO: Define navigation structure for all other source files.

workflow-templates/assets/mkdocs/mkdocs.yml

@@ -0,0 +1,54 @@
+# "Check Website" workflow (MkDocs, Task)
+
+Workflow file: [check-mkdocs-task.yml](check-mkdocs-task.yml)
+
+Check for problems with a [MkDocs](https://www.mkdocs.org/)-based static website.
+
+This is the version of the workflow for projects using the [Task](https://taskfile.dev/#/) task runner tool.
+
+## Installation
+
+See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs-poetry.md#installation)
+
+## Assets
+
+- [`Taskfile.yml`](assets/check-yaml-task/Taskfile.yml] - Build task.
+  - Install to: repository root (or add the `website:build` task into the existing `Taskfile.yml`)
+- [`Taskfile.yml`](assets/shared/Taskfile.yml] - Installation task.
+  - Add the `poetry:install-deps` task into the existing `Taskfile.yml`
+- Website assets - See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs-poetry.md#assets).
+
+## Readme badge
+
+Markdown badge:
+
+```markdown
+[![Check Website status](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/check-mkdocs-task.yml/badge.svg)](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/check-mkdocs-task.yml)
+```
+
+Replace the `REPO_OWNER` and `REPO_NAME` placeholders in the URLs with the final repository owner and name ([example](https://raw.githubusercontent.com/arduino-libraries/ArduinoIoTCloud/master/README.md)).
+
+---
+
+Asciidoc badge:
+
+```adoc
+image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-mkdocs-task.yml/badge.svg["Check Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-mkdocs-task.yml"]
+```
+
+Define the `{repository-owner}` and `{repository-name}` attributes and use them throughout the readme ([example](https://raw.githubusercontent.com/arduino-libraries/WiFiNINA/master/README.adoc)).
+
+## Commit message
+
+```
+Add CI workflow to check for problems with MkDocs-based website
+
+On every push or pull request that affects the source and configuration for the repository's MkDocs-based static
+website, build the site and fail if any problems were encountered.
+```
+
+## PR message
+
+```markdown
+On every push or pull request that affects the source and configuration for the repository's [MkDocs](https://www.mkdocs.org/)-based static website, build the site and fail if any problems were encountered.
+```

workflow-templates/check-mkdocs-task.md

@@ -0,0 +1,48 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md
+name: Check Website
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  pull_request:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Build website
+        run: task website:check

workflow-templates/check-mkdocs-task.yml

@@ -0,0 +1,48 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md
+name: Check Website
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  pull_request:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Build website
+        run: task website:check

workflow-templates/dependabot/workflow-template-copies/.github/workflows/check-mkdocs-task.yml

@@ -0,0 +1,39 @@
+# Source: https://github.com/arduino/.github/blob/master/workflow-templates/deploy-mkdocs-poetry.md
+name: Deploy Website
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    branches:
+      # TODO: Replace "main" below with default branch name if different.
+      - main
+    paths:
+      - ".github/workflows/deploy-mkdocs-poetry.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install Dependencies
+        run: poetry install --no-root
+
+      - name: Deploy website
+        run: poetry run mkdocs gh-deploy

workflow-templates/dependabot/workflow-template-copies/.github/workflows/deploy-mkdocs-poetry.yml

@@ -0,0 +1,78 @@
+# "Deploy Website" workflow (MkDocs, Poetry)
+
+Workflow file: [deploy-mkdocs-poetry.yml](deploy-mkdocs-poetry.yml)
+
+Deploy a [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).
+
+This is the version of the workflow for projects using the [Poetry](https://python-poetry.org/) dependency management tool.
+
+## Installation
+
+The website build dependencies are managed by [Poetry](https://python-poetry.org/).
+
+Install Poetry by following these instructions:<br />
+https://python-poetry.org/docs/#installation
+
+If your project does not already use Poetry, you can initialize the [`pyproject.toml`](https://python-poetry.org/docs/pyproject/) file using these commands:
+
+```
+poetry init --python="^3.9" --dev-dependency="mkdocs@^1.2.1" --dev-dependency="mkdocs-material@^7.1.8" --dev-dependency="mdx_truly_sane_lists@^1.2"
+poetry install
+```
+
+If already using Poetry, add the tool using this command:
+
+```
+poetry add --dev "mkdocs@^1.2.1" "mkdocs-material@^7.1.8" "mdx_truly_sane_lists@^1.2"
+```
+
+Make sure to commit the resulting `pyproject.toml` and `poetry.lock` files.
+
+## Assets
+
+- [mkdocs.yml](assets/mkdocs/mkdocs.yml) - base MkDocs configuration file.
+  - Install to: repository root
+- [icon_mac_light.png](assets/mkdocs/icon_mac_light.png) - Arduino logo for the website. **NOTE**: only for use in official Arduino projects. Community projects should use [the Community Logo](https://www.arduino.cc/en/Trademark/CommunityLogo).
+  - Install to: `docs/img/`
+
+## Readme badge
+
+Markdown badge:
+
+```markdown
+[![Deploy MkDocs Website status](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-mkdocs-poetry.yml/badge.svg)](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-mkdocs-poetry.yml)
+```
+
+Replace the `REPO_OWNER` and `REPO_NAME` placeholders in the URLs with the final repository owner and name ([example](https://raw.githubusercontent.com/arduino-libraries/ArduinoIoTCloud/master/README.md)).
+
+---
+
+Asciidoc badge:
+
+```adoc
+image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-mkdocs-poetry.yml/badge.svg["Deploy MkDocs Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-mkdocs-poetry.yml"]
+```
+
+Define the `{repository-owner}` and `{repository-name}` attributes and use them throughout the readme ([example](https://raw.githubusercontent.com/arduino-libraries/WiFiNINA/master/README.adoc)).
+
+## Commit message
+
+```
+Add CI workflow to deploy a MkDocs-based website to GitHub Pages
+
+On every push to the repository's default branch, deploy the repository's MkDocs-based static website to GitHub Pages.
+```
+
+## PR message
+
+```markdown
+On every push to the repository's default branch, deploy the repository's [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).
+```
+
+## Related
+
+- ["Check MkDocs Website" workflow](check-mkdocs.md)
+- ["Check Markdown" workflow](check-markdown.md)
+- ["Check Prettier Formatting" workflow](check-prettier-formatting.md)
+- ["Spell Check" workflow](spell-check.md)
+- ["Check YAML" workflow](check-yaml.md)

workflow-templates/deploy-mkdocs-poetry.md

@@ -0,0 +1,39 @@
+# Source: https://github.com/arduino/.github/blob/master/workflow-templates/deploy-mkdocs-poetry.md
+name: Deploy Website
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    branches:
+      # TODO: Replace "main" below with default branch name if different.
+      - main
+    paths:
+      - ".github/workflows/deploy-mkdocs-poetry.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install Dependencies
+        run: poetry install --no-root
+
+      - name: Deploy website
+        run: poetry run mkdocs gh-deploy