Skip to content

Commit f04d18f

Browse files
per1234per1234
authored
[skip changelog] Sync documentation assets with templates (#1383)
* [skip changelog] Sync documentation assets with templates We have assembled a collection of reusable project assets: https://github.com/arduino/tooling-project-assets These assets will be used in the repositories of all Arduino tooling projects. Some significant improvements and standardizations have been made in the upstream "template" assets, and those are introduced to this repository here. Notable: - Use markdownlint to check for common problems and formatting. - Make link check task Windows compatible - Streamline website versioning system - Use modern MkDocs versioning features - Make command reference generation task Windows compatible - Consolidate all Python dependency management to Poetry - Standardize documentation-related task names and deprecate old task names * Remove obsolete documentation tasks The sync with the template documentation assets has resulted in new standardized names for some of the documentation management tasks: - `docs:gen:commands` -> `go:cli-docs` - `docs:gen` -> `docs:generate` - `docs:build` -> `docs:check` - `docs:serve` -> `website:serve` - `docs:check-links` -> `markdown:check-links` * [skip changelog] Use standard list prefix in Markdown This is the standardized ordered list prefix for use in all Arduino Tooling Markdown files. The Markdown renderer will automatically handle numbering. Manual numbering means that either all following list items need to be renumbered every time a list item is added or removed, resulting in more work for contributors and reviewers. * [skip changelog] Use standardized Markdown code block style "Code fencing" is superior to the indentation code block syntax of Markdown because it permits syntax highlighting. Even in cases where syntax highlighting is not applicable, a consistent style should be used throughout all the Markdown files of Arduino Tooling projects.
1 parent a067638 commit f04d18f

25 files changed

+1205
-699
lines changed

‎.github/workflows/check-markdown-task.yml

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
2+
name: Check Markdown
3+
4+
env:
5+
# See: https://github.com/actions/setup-go/tree/v2#readme
6+
GO_VERSION: "1.16"
7+
8+
# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
9+
on:
10+
push:
11+
paths:
12+
- ".github/workflows/check-markdown-task.ya?ml"
13+
- ".markdown-link-check.json"
14+
- "Taskfile.ya?ml"
15+
- "**/.markdownlint*"
16+
- "**.go"
17+
- "**.mdx?"
18+
- "**.mkdn"
19+
- "**.mdown"
20+
- "**.markdown"
21+
- "rpc/**"
22+
pull_request:
23+
paths:
24+
- ".github/workflows/check-markdown-task.ya?ml"
25+
- ".markdown-link-check.json"
26+
- "Taskfile.ya?ml"
27+
- "**/.markdownlint*"
28+
- "**.go"
29+
- "**.mdx?"
30+
- "**.mkdn"
31+
- "**.mdown"
32+
- "**.markdown"
33+
- "rpc/**"
34+
schedule:
35+
# Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
36+
- cron: "0 8 * * TUE"
37+
workflow_dispatch:
38+
repository_dispatch:
39+
40+
jobs:
41+
lint:
42+
runs-on: ubuntu-latest
43+
44+
steps:
45+
- name: Checkout repository
46+
uses: actions/checkout@v2
47+
48+
- name: Initialize markdownlint-cli problem matcher
49+
uses: xt0rted/markdownlint-problem-matcher@v1
50+
51+
- name: Install Task
52+
uses: arduino/setup-task@v1
53+
with:
54+
repo-token: ${{ secrets.GITHUB_TOKEN }}
55+
version: 3.x
56+
57+
- name: Lint
58+
run: task markdown:lint
59+
60+
links:
61+
runs-on: ubuntu-latest
62+
63+
steps:
64+
- name: Checkout repository
65+
uses: actions/checkout@v2
66+
67+
- name: Install Go
68+
uses: actions/setup-go@v2
69+
with:
70+
go-version: ${{ env.GO_VERSION }}
71+
72+
- name: Install Go dependencies
73+
run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
74+
75+
- name: Install protoc compiler
76+
uses: arduino/setup-protoc@v1
77+
with:
78+
repo-token: ${{ secrets.GITHUB_TOKEN }}
79+
80+
- name: Install Task
81+
uses: arduino/setup-task@v1
82+
with:
83+
repo-token: ${{ secrets.GITHUB_TOKEN }}
84+
version: 3.x
85+
86+
- name: Check links
87+
run: task --silent markdown:check-links

‎.github/workflows/check-mkdocs-task.yml

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md
2+
name: Check Website
3+
4+
env:
5+
# See: https://github.com/actions/setup-go/tree/v2#readme
6+
GO_VERSION: "1.16"
7+
# See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python
8+
PYTHON_VERSION: "3.9"
9+
10+
# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
11+
on:
12+
push:
13+
paths:
14+
- ".github/workflows/check-mkdocs-task.ya?ml"
15+
- "Taskfile.ya?ml"
16+
- "mkdocs.ya?ml"
17+
- "poetry.lock"
18+
- "pyproject.toml"
19+
- "docs/**"
20+
pull_request:
21+
paths:
22+
- ".github/workflows/check-mkdocs-task.ya?ml"
23+
- "Taskfile.ya?ml"
24+
- "mkdocs.ya?ml"
25+
- "poetry.lock"
26+
- "pyproject.toml"
27+
- "docs/**"
28+
workflow_dispatch:
29+
repository_dispatch:
30+
31+
jobs:
32+
check:
33+
runs-on: ubuntu-latest
34+
35+
steps:
36+
- name: Checkout repository
37+
uses: actions/checkout@v2
38+
39+
- name: Install Go
40+
uses: actions/setup-go@v2
41+
with:
42+
go-version: ${{ env.GO_VERSION }}
43+
44+
- name: Install Go dependencies
45+
run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
46+
47+
- name: Install protoc compiler
48+
uses: arduino/setup-protoc@v1
49+
with:
50+
repo-token: ${{ secrets.GITHUB_TOKEN }}
51+
52+
- name: Install Python
53+
uses: actions/setup-python@v2
54+
with:
55+
python-version: ${{ env.PYTHON_VERSION }}
56+
57+
- name: Install Poetry
58+
run: pip install poetry
59+
60+
- name: Install Task
61+
uses: arduino/setup-task@v1
62+
with:
63+
repo-token: ${{ secrets.GITHUB_TOKEN }}
64+
version: 3.x
65+
66+
- name: Build website
67+
run: task website:check

‎.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md
2+
name: Deploy Website
3+
4+
env:
5+
# See: https://github.com/actions/setup-go/tree/v2#readme
6+
GO_VERSION: "1.16"
7+
# See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python
8+
PYTHON_VERSION: "3.9"
9+
10+
on:
11+
push:
12+
branches:
13+
# Branch to base "dev" website on. Set in siteversion.py also.
14+
- master
15+
# Release branches have names like 0.8.x, 0.9.x, ...
16+
- "[0-9]+.[0-9]+.x"
17+
paths:
18+
- "docs/**"
19+
- ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml"
20+
- "go.mod"
21+
- "go.sum"
22+
- "Taskfile.ya?ml"
23+
- "**.go"
24+
- "docsgen/**"
25+
- "rpc/**"
26+
- "mkdocs.ya?ml"
27+
- "poetry.lock"
28+
- "pyproject.toml"
29+
# Run on branch or tag creation (will be filtered by the publish-determination job).
30+
create:
31+
32+
jobs:
33+
publish-determination:
34+
runs-on: ubuntu-latest
35+
outputs:
36+
result: ${{ steps.determination.outputs.result }}
37+
steps:
38+
- name: Determine if documentation should be published on this workflow run
39+
id: determination
40+
run: |
41+
RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
42+
if [[ "${{ github.event_name }}" == "push" || ( "${{ github.event_name }}" == "create" && "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX ) ]]; then
43+
RESULT="true"
44+
else
45+
RESULT="false"
46+
fi
47+
48+
echo "::set-output name=result::$RESULT"
49+
50+
publish:
51+
runs-on: ubuntu-latest
52+
needs: publish-determination
53+
if: needs.publish-determination.outputs.result == 'true'
54+
55+
steps:
56+
- name: Checkout repository
57+
uses: actions/checkout@v2
58+
59+
- name: Install Go
60+
uses: actions/setup-go@v2
61+
with:
62+
go-version: ${{ env.GO_VERSION }}
63+
64+
- name: Install Go dependencies
65+
run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
66+
67+
- name: Install protoc compiler
68+
uses: arduino/setup-protoc@v1
69+
with:
70+
repo-token: ${{ secrets.GITHUB_TOKEN }}
71+
72+
- name: Install Python
73+
uses: actions/setup-python@v2
74+
with:
75+
python-version: ${{ env.PYTHON_VERSION }}
76+
77+
- name: Install Poetry
78+
run: |
79+
python -m pip install --upgrade pip
80+
python -m pip install poetry
81+
82+
- name: Install Task
83+
uses: arduino/setup-task@v1
84+
with:
85+
repo-token: ${{ secrets.GITHUB_TOKEN }}
86+
version: 3.x
87+
88+
- name: Create all generated documentation content
89+
run: task docs:generate
90+
91+
- name: Install Python dependencies
92+
run: poetry install --no-root
93+
94+
- name: Determine versioning parameters
95+
id: determine-versioning
96+
run: echo "::set-output name=data::$(poetry run python docs/siteversion/siteversion.py)"
97+
98+
- name: Publish documentation
99+
if: fromJson(steps.determine-versioning.outputs.data).version != null
100+
run: |
101+
# Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
102+
git config --global user.email "[email protected]"
103+
git config --global user.name "ArduinoBot"
104+
git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
105+
poetry run mike deploy \
106+
--update-aliases \
107+
--push \
108+
--remote origin \
109+
${{ fromJson(steps.determine-versioning.outputs.data).version }} \
110+
${{ fromJson(steps.determine-versioning.outputs.data).alias }}

‎.github/workflows/link-validation.yaml

-62
This file was deleted.

0 commit comments

Comments
 (0)