Skip to content

Commit ae1dc63

Browse files
gregghgreggh
committed
Refactor: Move documentation validation to dedicated workflow
1 parent 366d1e2 commit ae1dc63

2 files changed

Lines changed: 135 additions & 99 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -99,102 +99,4 @@ jobs:
9999
./scripts/test.sh
100100
continue-on-error: false
101101

102-
documentation:
103-
needs: [lint, test]
104-
if: github.ref == 'refs/heads/main'
105-
runs-on: ubuntu-latest
106-
steps:
107-
- uses: actions/checkout@v3
108-
109-
- name: Install Lua
110-
uses: leafo/gh-actions-lua@v9
111-
with:
112-
luaVersion: "5.1"
113-
114-
- name: Install LuaRocks
115-
uses: leafo/gh-actions-luarocks@v4
116-
117-
- name: Create cache directories
118-
run: mkdir -p ~/.luarocks
119-
120-
- name: Cache LuaRocks dependencies
121-
uses: actions/cache@v3
122-
with:
123-
path: ~/.luarocks
124-
key: ${{ runner.os }}-luarocks-docs-${{ hashFiles('**/*.rockspec') }}
125-
restore-keys: |
126-
${{ runner.os }}-luarocks-docs-
127-
128-
- name: Install dependencies for ldoc
129-
run: |
130-
# Install dependencies required by ldoc
131-
sudo apt-get update
132-
sudo apt-get install -y lua-discount
133-
134-
- name: Install ldoc
135-
run: luarocks install ldoc
136-
137-
- name: Verify ldoc installation
138-
run: |
139-
which ldoc || echo "ldoc not found in PATH"
140-
ldoc --version || echo "ldoc command failed"
141-
142-
- name: Generate API documentation
143-
run: |
144-
mkdir -p doc/luadoc
145-
if [ -f .ldoc.cfg ]; then
146-
# Run LDoc with warnings but don't fail on warnings
147-
ldoc -v lua/ -d doc/luadoc -c .ldoc.cfg
148-
else
149-
echo "No .ldoc.cfg found, skipping documentation generation"
150-
fi
151-
152-
- name: List generated documentation
153-
run: ls -la doc/luadoc || echo "No documentation generated"
154-
155-
- name: Install markdownlint-cli
156-
run: npm install -g markdownlint-cli@0.37.0
157-
158-
- name: Run markdownlint
159-
run: markdownlint '**/*.md' --config .markdownlint.json || true
160-
161-
- name: Link Checker
162-
uses: lycheeverse/lychee-action@v1.8.0
163-
with:
164-
args: --verbose --no-progress '**/*.md'
165-
env:
166-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
167-
168-
- name: Check Lua code blocks in markdown
169-
run: |
170-
find . -type f -name "*.md" -exec grep -l '```lua' {} \; | while read -r file; do
171-
echo "Checking Lua snippets in $file"
172-
173-
# Create a temporary directory for the snippets
174-
TEMP_DIR=$(mktemp -d)
175-
176-
# Extract Lua code blocks
177-
grep -n '^```lua$' "$file" | while read -r line_start; do
178-
# Get the line number where the lua block starts
179-
line_num=$(echo "$line_start" | cut -d: -f1)
180-
181-
# Find the line number where the next ``` appears
182-
line_end=$(tail -n +$((line_num+1)) "$file" | grep -n '^```$' | head -1 | cut -d: -f1)
183-
if [ -n "$line_end" ]; then
184-
line_end=$((line_num + line_end))
185-
186-
# Extract the lua snippet
187-
snippet_file="${TEMP_DIR}/snippet_${line_num}.lua"
188-
sed -n "$((line_num+1)),$((line_end-1))p" "$file" > "$snippet_file"
189-
190-
# Check syntax if file is not empty
191-
if [ -s "$snippet_file" ]; then
192-
echo " Checking snippet starting at line $line_num in $file"
193-
luac -p "$snippet_file" || echo "Syntax error in $file at line $line_num"
194-
fi
195-
fi
196-
done
197-
198-
# Clean up
199-
rm -rf "$TEMP_DIR"
200-
done
102+
# Documentation validation has been moved to the dedicated docs.yml workflow

‎.github/workflows/docs.yml‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'docs/**'
8+
- 'README.md'
9+
- 'CONTRIBUTING.md'
10+
- 'DEVELOPMENT.md'
11+
- 'CHANGELOG.md'
12+
- '.github/workflows/docs.yml'
13+
pull_request:
14+
branches: [ main ]
15+
paths:
16+
- 'docs/**'
17+
- 'README.md'
18+
- 'CONTRIBUTING.md'
19+
- 'DEVELOPMENT.md'
20+
- 'CHANGELOG.md'
21+
- '.github/workflows/docs.yml'
22+
workflow_dispatch:
23+
24+
jobs:
25+
markdown-lint:
26+
name: Markdown Lint
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v4
30+
31+
- name: Install markdownlint-cli
32+
run: npm install -g markdownlint-cli@0.37.0
33+
34+
- name: Run markdownlint
35+
run: markdownlint '**/*.md' --config .markdownlint.json || true
36+
37+
check-links:
38+
name: Check Links
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- name: Link Checker
44+
uses: lycheeverse/lychee-action@v1.8.0
45+
with:
46+
args: --verbose --no-progress '**/*.md'
47+
env:
48+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
49+
50+
validate-lua-examples:
51+
name: Validate Lua Examples
52+
runs-on: ubuntu-latest
53+
steps:
54+
- uses: actions/checkout@v4
55+
56+
- name: Setup Lua
57+
uses: leafo/gh-actions-lua@v10
58+
with:
59+
luaVersion: "5.1"
60+
61+
- name: Check Lua code blocks in markdown
62+
run: |
63+
find . -type f -name "*.md" -exec grep -l '```lua' {} \; | while read -r file; do
64+
echo "Checking Lua snippets in $file"
65+
66+
# Create a temporary directory for the snippets
67+
TEMP_DIR=$(mktemp -d)
68+
69+
# Extract Lua code blocks
70+
grep -n '^```lua$' "$file" | while read -r line_start; do
71+
# Get the line number where the lua block starts
72+
line_num=$(echo "$line_start" | cut -d: -f1)
73+
74+
# Find the line number where the next ``` appears
75+
line_end=$(tail -n +$((line_num+1)) "$file" | grep -n '^```$' | head -1 | cut -d: -f1)
76+
if [ -n "$line_end" ]; then
77+
line_end=$((line_num + line_end))
78+
79+
# Extract the lua snippet
80+
snippet_file="${TEMP_DIR}/snippet_${line_num}.lua"
81+
sed -n "$((line_num+1)),$((line_end-1))p" "$file" > "$snippet_file"
82+
83+
# Check syntax if file is not empty
84+
if [ -s "$snippet_file" ]; then
85+
echo " Checking snippet starting at line $line_num in $file"
86+
luac -p "$snippet_file" || echo "Syntax error in $file at line $line_num"
87+
fi
88+
fi
89+
done
90+
91+
# Clean up
92+
rm -rf "$TEMP_DIR"
93+
done
94+
95+
generate-api-docs:
96+
name: Generate API Documentation
97+
runs-on: ubuntu-latest
98+
steps:
99+
- uses: actions/checkout@v4
100+
101+
- name: Install Lua
102+
uses: leafo/gh-actions-lua@v10
103+
with:
104+
luaVersion: "5.1"
105+
106+
- name: Install LuaRocks
107+
uses: leafo/gh-actions-luarocks@v4
108+
109+
- name: Install dependencies for ldoc
110+
run: |
111+
# Install dependencies required by ldoc
112+
sudo apt-get update
113+
sudo apt-get install -y lua-discount
114+
115+
- name: Install ldoc
116+
run: luarocks install ldoc
117+
118+
- name: Verify ldoc installation
119+
run: |
120+
which ldoc || echo "ldoc not found in PATH"
121+
ldoc --version || echo "ldoc command failed"
122+
123+
- name: Generate API documentation
124+
run: |
125+
mkdir -p doc/luadoc
126+
if [ -f .ldoc.cfg ]; then
127+
# Run LDoc with warnings but don't fail on warnings
128+
ldoc -v lua/ -d doc/luadoc -c .ldoc.cfg || echo "ldoc generation failed, but continuing"
129+
else
130+
echo "No .ldoc.cfg found, skipping documentation generation"
131+
fi
132+
133+
- name: List generated documentation
134+
run: ls -la doc/luadoc || echo "No documentation generated"

0 commit comments

Comments
 (0)