Skip to content

Commit 4ccabd8

Browse files
per1234per1234
committed
Add documentation website
A static website containing documentation is hosted on GitHub Pages. The source is the Markdown files stored in the `docs` subfolder, as well as the CLI documentation generated by Cobra. The documentation is versioned, so the user can access the documentation associated with: - The development version (tip of the default branch). - The latest release version. - Any specific release version.
1 parent 592badc commit 4ccabd8

17 files changed

+2374
-13
lines changed

‎.github/workflows/check-links.yml

+31
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ on:
1818
jobs:
1919
check-links:
2020
runs-on: ubuntu-latest
21+
22+
env:
23+
DOCUMENTATION_REQUIREMENTS_PATH: ./docs/requirements_docs.txt
24+
2125
steps:
2226
- name: Checkout local repository
2327
uses: actions/checkout@v2
@@ -28,5 +32,32 @@ jobs:
2832
repo-token: ${{ secrets.GITHUB_TOKEN }}
2933
version: 3.x
3034

35+
- name: Install Go
36+
uses: actions/setup-go@v2
37+
with:
38+
go-version: "1.14"
39+
40+
- name: Install Python
41+
uses: actions/setup-python@v2
42+
with:
43+
python-version: "3.8"
44+
45+
- name: Cache dependencies
46+
uses: actions/cache@v2
47+
with:
48+
path: ~/.cache/pip
49+
key: ${{ runner.os }}-pip-${{ hashFiles(env.DOCUMENTATION_REQUIREMENTS_PATH) }}
50+
restore-keys: |
51+
${{ runner.os }}-pip-
52+
53+
- name: Install Python dependencies
54+
run: |
55+
python -m pip install --upgrade pip
56+
python -m pip install --requirement "${{ env.DOCUMENTATION_REQUIREMENTS_PATH }}"
57+
58+
- name: Build documentation website
59+
# Ensure the documentation can build. These docs won't be published.
60+
run: task docs:build
61+
3162
- name: Check links
3263
run: task --silent docs:check-links

‎.github/workflows/publish-docs.yml

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Publish documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
# Release branches have names like 0.8.x, 0.9.x, ...
8+
- "[0-9]+.[0-9]+.x"
9+
paths:
10+
- "docs/**"
11+
- "docsgen/**"
12+
- "cli/**"
13+
- ".github/workflows/publish-docs.yml"
14+
# Run on branch or tag creation (will be filtered by the publish-determination job).
15+
create:
16+
17+
jobs:
18+
publish-determination:
19+
runs-on: ubuntu-latest
20+
outputs:
21+
result: ${{ steps.determination.outputs.result }}
22+
steps:
23+
- name: Determine if documentation should be published on this workflow run
24+
id: determination
25+
run: |
26+
RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
27+
if [[ "${{ github.event_name }}" == "push" || ( "${{ github.event_name }}" == "create" && "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX ) ]]; then
28+
RESULT="true"
29+
else
30+
RESULT="false"
31+
fi
32+
33+
echo "::set-output name=result::$RESULT"
34+
35+
publish:
36+
runs-on: ubuntu-latest
37+
needs: publish-determination
38+
if: needs.publish-determination.outputs.result == 'true'
39+
40+
env:
41+
DOCUMENTATION_REQUIREMENTS_PATH: ./requirements_docs.txt
42+
43+
steps:
44+
- name: Checkout local repository
45+
uses: actions/checkout@v2
46+
47+
- name: Install Taskfile
48+
uses: arduino/actions/setup-taskfile@master
49+
with:
50+
repo-token: ${{ secrets.GITHUB_TOKEN }}
51+
version: 3.x
52+
53+
- name: Install Go
54+
uses: actions/setup-go@v2
55+
with:
56+
go-version: "1.14"
57+
58+
- name: Install Python
59+
uses: actions/setup-python@v2
60+
with:
61+
python-version: "3.8"
62+
63+
- name: Cache dependencies
64+
uses: actions/cache@v2
65+
with:
66+
path: ~/.cache/pip
67+
key: ${{ runner.os }}-pip-${{ hashFiles(env.DOCUMENTATION_REQUIREMENTS_PATH) }}
68+
restore-keys: |
69+
${{ runner.os }}-pip-
70+
71+
- name: Install Python dependencies
72+
run: |
73+
python -m pip install --upgrade pip
74+
python -m pip install --requirement "${{ env.DOCUMENTATION_REQUIREMENTS_PATH }}"
75+
76+
- name: Publish documentation
77+
# Determine docs version for the commit pushed and publish accordingly using Mike.
78+
# Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
79+
run: |
80+
git config --global user.email "[email protected]"
81+
git config --global user.name "ArduinoBot"
82+
git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
83+
python docs/build.py

‎.github/workflows/validate-docs.yml

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Validate documentation
2+
3+
on:
4+
pull_request:
5+
paths:
6+
# existing docs
7+
- "docs/**"
8+
# changes to the cli reference generator
9+
- "docsgen/**"
10+
# potential changes to commands documentation
11+
- "cli/**"
12+
# changes to the workflow itself
13+
- ".github/workflows/validate-docs.yml"
14+
push:
15+
paths:
16+
- "docs/**"
17+
- "docsgen/**"
18+
- "cli/**"
19+
- "rpc/**"
20+
- ".github/workflows/validate-docs.yml"
21+
22+
jobs:
23+
validate:
24+
runs-on: ubuntu-latest
25+
26+
env:
27+
DOCUMENTATION_REQUIREMENTS_PATH: ./requirements_docs.txt
28+
29+
steps:
30+
- name: Checkout local repository
31+
uses: actions/checkout@v2
32+
33+
- name: Install Taskfile
34+
uses: arduino/actions/setup-taskfile@master
35+
with:
36+
repo-token: ${{ secrets.GITHUB_TOKEN }}
37+
version: 3.x
38+
39+
- name: Install Go
40+
uses: actions/setup-go@v2
41+
with:
42+
go-version: "1.14"
43+
44+
- name: Install Python
45+
uses: actions/setup-python@v2
46+
with:
47+
python-version: "3.8"
48+
49+
- name: Cache dependencies
50+
uses: actions/cache@v2
51+
with:
52+
path: ~/.cache/pip
53+
key: ${{ runner.os }}-pip-${{ hashFiles(env.DOCUMENTATION_REQUIREMENTS_PATH) }}
54+
restore-keys: |
55+
${{ runner.os }}-pip-
56+
57+
- name: Install Python dependencies
58+
run: |
59+
python -m pip install --upgrade pip
60+
python -m pip install --requirement "${{ env.DOCUMENTATION_REQUIREMENTS_PATH }}"
61+
62+
- name: Build documentation website
63+
# Ensure the documentation can build. These docs won't be published.
64+
run: task docs:build

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,9 @@ coverage_unit.txt
1212
*.bak
1313
*.code-workspace
1414
*.sublime-workspace
15+
16+
# MkDocs
17+
/site/
18+
/docsgen/arduino-cli
19+
/docsgen/arduino-cli.exe
20+
/docs/commands/*.md

‎README.md

+1-12
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,4 @@
66
- Sketches
77
- Libraries
88

9-
## Usage
10-
11-
After installing `arduino-lint`, run the command `arduino-lint --help` for usage documentation.
12-
13-
A few additional configuration options only of use for internal/development use of the tool can be set via environment
14-
variables:
15-
16-
- `ARDUINO_LINT_OFFICIAL` - Set to `"true"` to run the checks that only apply to official Arduino projects.
17-
- `ARDUINO_LINT_LOG_LEVEL` - Messages with this level and above will be logged.
18-
- Supported values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`
19-
- `ARDUINO_LINT_LOG_FORMAT` - The output format for the logs.
20-
- Supported values: `text`, `json`
9+
For usage instructions, see [the documentation](https://arduino.github.io/arduino-lint/latest/)

‎Taskfile.yml

+38-1
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,39 @@ tasks:
114114
- poetry install --no-root
115115
- poetry run black .
116116

117+
docs:gen:
118+
desc: Generate command reference
119+
dir: ./docsgen
120+
cmds:
121+
# docs will generate examples using os.Args[0] so we need to call
122+
# the generator `arduino-lint`
123+
- go build -o arduino-lint{{exeExt}}
124+
# we invoke `arduino-lint` like this instead of `./arduino-lint` to remove
125+
# the `./` chars from the examples
126+
- PATH=. arduino-lint ../docs/commands
127+
- task: docs:format
128+
129+
docs:build:
130+
desc: Build documentation website contents
131+
deps:
132+
- docs:gen
133+
cmds:
134+
- mkdocs build --strict
135+
136+
docs:publish:
137+
desc: Use Mike to build and push versioned docs
138+
deps:
139+
- docs:gen
140+
cmds:
141+
- mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}
142+
143+
docs:serve:
144+
desc: Run documentation website locally
145+
deps:
146+
- docs:build
147+
cmds:
148+
- mkdocs serve
149+
117150
docs:check:
118151
desc: Lint and check formatting of documentation files
119152
cmds:
@@ -228,9 +261,13 @@ vars:
228261

229262
GOLINTFLAGS: "-min_confidence 0.8 -set_exit_status"
230263

264+
DOCS_VERSION: dev
265+
DOCS_ALIAS: ""
266+
DOCS_REMOTE: "origin"
267+
231268
PRETTIER: [email protected]
232269

233270
WORKFLOW_SCHEMA_PATH: "$(mktemp -t gha-workflow-schema-XXXXXXXXXX.json)"
234271

235-
CODESPELL_SKIP_OPTION: '--skip "./.git,./go.mod,./go.sum,./arduino-lint,./arduino-lint.exe,./check/checkfunctions/testdata/libraries/MisspelledSentenceParagraphValue/library.properties"'
272+
CODESPELL_SKIP_OPTION: '--skip "./.git,go.mod,go.sum,./arduino-lint,./arduino-lint.exe,./check/checkfunctions/testdata/libraries/MisspelledSentenceParagraphValue/library.properties,./site"'
236273
CODESPELL_IGNORE_WORDS_OPTION: "--ignore-words ./etc/codespell-ignore-words-list.txt"

0 commit comments

Comments
 (0)