Skip to content

Commit 54e1502

Browse files
per1234per1234
authored
Merge pull request #111 from arduino/per1234/docs
Add documentation website
2 parents 107b0ca + 0f55d25 commit 54e1502

18 files changed

+2817
-22
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 Poetry
54+
run: |
55+
python -m pip install --upgrade pip
56+
python -m pip install poetry
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+
steps:
41+
- name: Checkout local repository
42+
uses: actions/checkout@v2
43+
44+
- name: Install Taskfile
45+
uses: arduino/actions/setup-taskfile@master
46+
with:
47+
repo-token: ${{ secrets.GITHUB_TOKEN }}
48+
version: 3.x
49+
50+
- name: Install Go
51+
uses: actions/setup-go@v2
52+
with:
53+
go-version: "1.14"
54+
55+
- name: Install Python
56+
uses: actions/setup-python@v2
57+
with:
58+
python-version: "3.8"
59+
60+
- name: Cache dependencies
61+
uses: actions/cache@v2
62+
with:
63+
path: ~/.cache/pip
64+
key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
65+
restore-keys: |
66+
${{ runner.os }}-pip-
67+
68+
- name: Install Poetry
69+
run: |
70+
python -m pip install --upgrade pip
71+
python -m pip install poetry
72+
73+
- name: Install Python dependencies
74+
run: poetry install --no-root
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+
poetry run python docs/build.py

‎.github/workflows/validate-docs.yml

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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+
steps:
27+
- name: Checkout local repository
28+
uses: actions/checkout@v2
29+
30+
- name: Install Taskfile
31+
uses: arduino/actions/setup-taskfile@master
32+
with:
33+
repo-token: ${{ secrets.GITHUB_TOKEN }}
34+
version: 3.x
35+
36+
- name: Install Go
37+
uses: actions/setup-go@v2
38+
with:
39+
go-version: "1.14"
40+
41+
- name: Install Python
42+
uses: actions/setup-python@v2
43+
with:
44+
python-version: "3.8"
45+
46+
- name: Cache dependencies
47+
uses: actions/cache@v2
48+
with:
49+
path: ~/.cache/pip
50+
key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
51+
restore-keys: |
52+
${{ runner.os }}-pip-
53+
54+
- name: Install Poetry
55+
run: |
56+
python -m pip install --upgrade pip
57+
python -m pip install poetry
58+
59+
- name: Build documentation website
60+
# Ensure the documentation can build. These docs won't be published.
61+
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

+36-1
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,37 @@ tasks:
115115
- poetry install --no-root
116116
- poetry run black .
117117

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

230261
GOLINTFLAGS: "-min_confidence 0.8 -set_exit_status"
231262

263+
DOCS_VERSION: dev
264+
DOCS_ALIAS: ""
265+
DOCS_REMOTE: "origin"
266+
232267
PRETTIER: [email protected]
233268

234269
WORKFLOW_SCHEMA_PATH: "$(mktemp -t gha-workflow-schema-XXXXXXXXXX.json)"
235270

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

0 commit comments

Comments
 (0)