Skip to content

Commit f8d38a4

Browse files
gregghgreggh
committed
Refactor: Move documentation validation to dedicated workflow
1 parent 9477952 commit f8d38a4

File tree

2 files changed

+130
-94
lines changed

2 files changed

+130
-94
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -124,97 +124,4 @@ jobs:
124124
run: |
125125
make test-debug
126126
127-
documentation:
128-
needs: [lint, test]
129-
if: github.ref == 'refs/heads/main'
130-
runs-on: ubuntu-latest
131-
steps:
132-
- uses: actions/checkout@v3
133-
134-
- name: Install Lua
135-
uses: leafo/gh-actions-lua@v9
136-
with:
137-
luaVersion: "5.1"
138-
139-
- name: Install LuaRocks
140-
uses: leafo/gh-actions-luarocks@v4
141-
142-
- name: Create cache directories
143-
run: mkdir -p ~/.luarocks
144-
145-
- name: Cache LuaRocks dependencies
146-
uses: actions/cache@v3
147-
with:
148-
path: ~/.luarocks
149-
key: ${{ runner.os }}-luarocks-docs-${{ hashFiles('**/*.rockspec') }}
150-
restore-keys: |
151-
${{ runner.os }}-luarocks-docs-
152-
153-
- name: Install dependencies for ldoc
154-
run: |
155-
# Install dependencies required by ldoc
156-
sudo apt-get update
157-
sudo apt-get install -y lua-discount
158-
159-
- name: Install ldoc
160-
run: luarocks install ldoc
161-
162-
- name: Verify ldoc installation
163-
run: |
164-
which ldoc || echo "ldoc not found in PATH"
165-
ldoc --version || echo "ldoc command failed"
166-
167-
- name: Generate API documentation
168-
run: |
169-
mkdir -p doc/luadoc
170-
ldoc lua/ -d doc/luadoc -c .ldoc.cfg || echo "ldoc generation failed, but continuing"
171-
172-
- name: List generated documentation
173-
run: ls -la doc/luadoc || echo "No documentation generated"
174-
175-
- name: Install markdownlint-cli
176-
run: npm install -g [email protected]
177-
178-
- name: Run markdownlint
179-
run: markdownlint '**/*.md' --config .markdownlint.json || true
180-
181-
- name: Link Checker
182-
uses: lycheeverse/[email protected]
183-
with:
184-
args: --verbose --no-progress '**/*.md'
185-
env:
186-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
187-
188-
- name: Check Lua code blocks in markdown
189-
run: |
190-
find . -type f -name "*.md" -exec grep -l '```lua' {} \; | while read -r file; do
191-
echo "Checking Lua snippets in $file"
192-
193-
# Create a temporary directory for the snippets
194-
TEMP_DIR=$(mktemp -d)
195-
196-
# Extract Lua code blocks
197-
grep -n '^```lua$' "$file" | while read -r line_start; do
198-
# Get the line number where the lua block starts
199-
line_num=$(echo "$line_start" | cut -d: -f1)
200-
201-
# Find the line number where the next ``` appears
202-
line_end=$(tail -n +$((line_num+1)) "$file" | grep -n '^```$' | head -1 | cut -d: -f1)
203-
if [ -n "$line_end" ]; then
204-
line_end=$((line_num + line_end))
205-
206-
# Extract the lua snippet
207-
snippet_file="${TEMP_DIR}/snippet_${line_num}.lua"
208-
sed -n "$((line_num+1)),$((line_end-1))p" "$file" > "$snippet_file"
209-
210-
# Check syntax if file is not empty
211-
if [ -s "$snippet_file" ]; then
212-
echo " Checking snippet starting at line $line_num in $file"
213-
luac -p "$snippet_file" || echo "Syntax error in $file at line $line_num"
214-
fi
215-
fi
216-
done
217-
218-
# Clean up
219-
rm -rf "$TEMP_DIR"
220-
done
127+
# Documentation validation has been moved to the dedicated docs.yml workflow

‎.github/workflows/docs.yml‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
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 [email protected]
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/[email protected]
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+
ldoc lua/ -d doc/luadoc -c .ldoc.cfg || echo "ldoc generation failed, but continuing"
127+
128+
- name: List generated documentation
129+
run: ls -la doc/luadoc || echo "No documentation generated"

0 commit comments

Comments
 (0)