Skip to content

Commit 58fa673

Browse files
per1234per1234
committed
Add template workflow to generate Cobra docs and deploy a versioned MkDocs-based website to GitHub Pages
On every push to the repository's default branch or release branch, generate a command line reference and deploy the repository's MkDocs-based static website to GitHub Pages. Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important for the reader to be able to access the documentation for the specific version of the project they are using. The documentation system provides access to: - The tip of the default branch ("dev") - The latest release ("latest") - Each minor version series (e.g., "1.2") The website version is selectable via a menu on the website as well as the URL of each documentation page. --- This workflow is based on the "Deploy Website" workflow (versioned, MkDocs, Poetry) template.
1 parent f2b4599 commit 58fa673

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

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

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

‎workflow-templates/deploy-cobra-mkdocs-versioned-poetry.yml

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

0 commit comments

Comments
 (0)