Skip to content

Commit 81d2d38

Browse files
per1234per1234
committed
Add infrastructure for managing table of contents
The project readme contains a table of contents in order to facilitate the navigation of the documentation. It is important that this table of contents is kept in sync with the documentation content. A task is added for automatically generating the ToC from the content of the file. A GitHub Actions workflow is added to check the table of contents. On every push or pull request that affects relevant files, it will check whether the table of contents matches the file structure.
1 parent 12ca286 commit 81d2d38

File tree

5 files changed

+1133
-0
lines changed

5 files changed

+1133
-0
lines changed

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

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-toc-task.md
2+
name: Check ToC
3+
4+
env:
5+
# See: https://github.com/actions/setup-node/#readme
6+
NODE_VERSION: 16.x
7+
8+
# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
9+
on:
10+
create:
11+
push:
12+
paths:
13+
- ".github/workflows/check-toc-task.ya?ml"
14+
- "package.json"
15+
- "package-lock.json"
16+
- "README.md"
17+
pull_request:
18+
paths:
19+
- ".github/workflows/check-toc-task.ya?ml"
20+
- "package.json"
21+
- "package-lock.json"
22+
- "README.md"
23+
schedule:
24+
# Run periodically to catch breakage caused by external changes.
25+
- cron: "0 3 * * WED"
26+
workflow_dispatch:
27+
repository_dispatch:
28+
29+
jobs:
30+
run-determination:
31+
runs-on: ubuntu-latest
32+
permissions: {}
33+
outputs:
34+
result: ${{ steps.determination.outputs.result }}
35+
steps:
36+
- name: Determine if the rest of the workflow should run
37+
id: determination
38+
run: |
39+
RELEASE_BRANCH_REGEX="^refs/heads/v[0-9]+$"
40+
# The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
41+
if [[
42+
"${{ github.event_name }}" != "create" ||
43+
"${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
44+
]]; then
45+
# Run the other jobs.
46+
RESULT="true"
47+
else
48+
# There is no need to run the other jobs.
49+
RESULT="false"
50+
fi
51+
52+
echo "result=$RESULT" >> $GITHUB_OUTPUT
53+
54+
check:
55+
name: ${{ matrix.file.name }}
56+
needs: run-determination
57+
if: needs.run-determination.outputs.result == 'true'
58+
runs-on: ubuntu-latest
59+
permissions:
60+
contents: read
61+
62+
strategy:
63+
fail-fast: false
64+
65+
matrix:
66+
file:
67+
- name: README.md
68+
# Max ToC depth, for use with the markdown-toc --maxdepth flag.
69+
maxdepth: 4
70+
71+
steps:
72+
- name: Checkout repository
73+
uses: actions/checkout@v4
74+
75+
- name: Setup Node.js
76+
uses: actions/setup-node@v4
77+
with:
78+
node-version: ${{ env.NODE_VERSION }}
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: Rebuild ToC
87+
run: |
88+
task markdown:toc \
89+
FILE_PATH="${{ github.workspace }}/${{ matrix.file.name }}" \
90+
MAX_DEPTH=${{ matrix.file.maxdepth }}
91+
92+
- name: Check ToC
93+
run: git diff --color --exit-code

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
[![Check Poetry status](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml)
66
[![Check Python status](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml)
77
[![Check Taskfiles status](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml)
8+
[![Check ToC status](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml)
89
[![Integration Tests](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml)
910
[![Spell Check status](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml)
1011
[![Sync Labels status](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml)

‎Taskfile.yml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ tasks:
2424
deps:
2525
- task: general:correct-spelling
2626
- task: markdown:fix
27+
- task: markdown:toc
2728
- task: poetry:sync
2829
- task: python:format
2930

@@ -101,6 +102,19 @@ tasks:
101102
cmds:
102103
- npx markdownlint-cli "**/*.md"
103104

105+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-toc-task/Taskfile.yml
106+
markdown:toc:
107+
desc: Update the table of contents
108+
deps:
109+
- task: npm:install-deps
110+
cmds:
111+
- |
112+
npx markdown-toc \
113+
--bullets=- \
114+
--maxdepth={{.MAX_DEPTH}} \
115+
-i \
116+
"{{.FILE_PATH}}"
117+
104118
# Parameter variables:
105119
# - PROJECT_PATH: path of the npm-managed project. Default value: "./"
106120
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml

0 commit comments

Comments
 (0)