Skip to content

Commit 6be7780

Browse files
JilocJiloc
committed
generate config docs on ci
1 parent 826c7cc commit 6be7780

File tree

2 files changed

+203
-0
lines changed

2 files changed

+203
-0
lines changed

‎.github/workflows/node-config-docsgen.yml

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
name: "Generate Node Configuration Documentation"
2+
3+
on:
4+
# Allow manual triggering
5+
workflow_dispatch:
6+
inputs:
7+
output-dir:
8+
description: "Output directory for generated documentation"
9+
required: false
10+
default: "./target/generated-docs"
11+
type: string
12+
min-doc-size:
13+
description: "Minimum documentation size in bytes"
14+
required: false
15+
default: "50000"
16+
type: string
17+
rust-nightly-version:
18+
description: "Specific nightly version to use (e.g., 'nightly-2025-06-17')"
19+
required: false
20+
default: "nightly-2025-06-17"
21+
type: string
22+
23+
# Allow being called by other workflows
24+
workflow_call:
25+
inputs:
26+
output-dir:
27+
description: "Output directory for generated documentation"
28+
required: false
29+
default: "./target/generated-docs"
30+
type: string
31+
min-doc-size:
32+
description: "Minimum documentation size in bytes"
33+
required: false
34+
default: "50000"
35+
type: string
36+
rust-nightly-version:
37+
description: "Specific nightly version to use (e.g., 'nightly-2025-06-17')"
38+
required: false
39+
default: "nightly-2025-06-17"
40+
type: string
41+
42+
jobs:
43+
generate-config-docs:
44+
name: Generate Configuration Documentation
45+
runs-on: ubuntu-latest
46+
47+
steps:
48+
## Checkout the code
49+
- name: Checkout the latest code
50+
id: git_checkout
51+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
52+
53+
## Install required system dependencies
54+
- name: Install system dependencies
55+
id: install_deps
56+
shell: bash
57+
run: |
58+
echo "Installing system dependencies..."
59+
sudo apt-get update -q
60+
sudo apt-get install -y jq
61+
62+
## Install Rust nightly toolchain (required for rustdoc JSON output)
63+
- name: Install Rust nightly toolchain
64+
id: install_rust
65+
uses: dtolnay/rust-toolchain@b3b07ba8b418998c39fb20f53e8b695cdcc8de1b # stable
66+
with:
67+
toolchain: ${{ inputs.rust-nightly-version || 'nightly-2025-06-17' }}
68+
components: rustdoc
69+
70+
## Cache Cargo dependencies
71+
- name: Cache Cargo dependencies
72+
id: cache_cargo
73+
uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
74+
with:
75+
path: |
76+
~/.cargo/registry/index/
77+
~/.cargo/registry/cache/
78+
~/.cargo/git/db/
79+
./target/
80+
key: ${{ runner.os }}-cargo-nightly-${{ hashFiles('**/Cargo.lock') }}
81+
restore-keys: |
82+
${{ runner.os }}-cargo-nightly-
83+
${{ runner.os }}-cargo-
84+
85+
## Generate configuration documentation
86+
- name: Generate Config Documentation
87+
id: generate_docs
88+
shell: bash
89+
run: |
90+
echo "Generating configuration documentation..."
91+
92+
# Set environment variables for the script
93+
export PROJECT_ROOT="$(pwd)"
94+
export OUTPUT_DIR="$(pwd)/${{ inputs.output-dir || './target/generated-docs' }}"
95+
96+
cd contrib/tools/config-docs-generator
97+
chmod +x generate-config-docs.sh
98+
./generate-config-docs.sh
99+
100+
# Verify output was generated
101+
if [[ ! -f "$OUTPUT_DIR/node-parameters.md" ]]; then
102+
echo "Error: Configuration documentation was not generated"
103+
echo "Expected file: $OUTPUT_DIR/node-parameters.md"
104+
exit 1
105+
fi
106+
107+
echo "Documentation generated successfully at $OUTPUT_DIR/node-parameters.md"
108+
109+
## Validate generated documentation quality
110+
- name: Validate Generated Documentation
111+
id: validate_docs
112+
shell: bash
113+
run: |
114+
echo "Validating generated documentation..."
115+
116+
MARKDOWN_FILE="${{ inputs.output-dir || './target/generated-docs' }}/node-parameters.md"
117+
118+
# Check if file exists and has content
119+
if [[ ! -f "$MARKDOWN_FILE" ]]; then
120+
echo "Error: Markdown file not found at $MARKDOWN_FILE"
121+
exit 1
122+
fi
123+
124+
# Check file size (should be substantial)
125+
FILE_SIZE=$(wc -c < "$MARKDOWN_FILE")
126+
MIN_SIZE=${{ inputs.min-doc-size || '50000' }}
127+
128+
if [[ $FILE_SIZE -lt $MIN_SIZE ]]; then
129+
echo "Error: Generated documentation is too small ($FILE_SIZE bytes, minimum $MIN_SIZE)"
130+
echo "This likely indicates a generation failure"
131+
exit 1
132+
fi
133+
134+
# Check word count and basic structure
135+
WORD_COUNT=$(wc -w < "$MARKDOWN_FILE")
136+
LINE_COUNT=$(wc -l < "$MARKDOWN_FILE")
137+
138+
echo "Documentation validation results:"
139+
echo " - File size: $FILE_SIZE bytes"
140+
echo " - Word count: $WORD_COUNT words"
141+
echo " - Line count: $LINE_COUNT lines"
142+
143+
# Basic content validation
144+
if ! grep -q "# Configuration Reference" "$MARKDOWN_FILE"; then
145+
echo "Warning: Documentation may be malformed - missing main title"
146+
fi
147+
148+
if [[ $WORD_COUNT -lt 100 ]]; then
149+
echo "Warning: Documentation seems very short ($WORD_COUNT words)"
150+
fi
151+
152+
echo "Documentation validation completed successfully ✅"
153+
154+
## Upload documentation as artifact
155+
- name: Upload Documentation Artifact
156+
id: upload_artifact
157+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
158+
with:
159+
name: "node-parameters.md"
160+
path: |
161+
${{ inputs.output-dir || './target/generated-docs' }}/*
162+
retention-days: 30
163+
if-no-files-found: error
164+
165+
## Generate job summary
166+
- name: Generate Job Summary
167+
id: summary
168+
shell: bash
169+
run: |
170+
echo "## Configuration Documentation Generated ✅" >> $GITHUB_STEP_SUMMARY
171+
echo "" >> $GITHUB_STEP_SUMMARY
172+
echo "The Stacks Core configuration documentation has been successfully generated and uploaded." >> $GITHUB_STEP_SUMMARY
173+
echo "" >> $GITHUB_STEP_SUMMARY
174+
175+
# Add file statistics if available
176+
MARKDOWN_FILE="${{ inputs.output-dir || './target/generated-docs' }}/node-parameters.md"
177+
if [[ -f "$MARKDOWN_FILE" ]]; then
178+
FILE_SIZE=$(wc -c < "$MARKDOWN_FILE")
179+
WORD_COUNT=$(wc -w < "$MARKDOWN_FILE")
180+
181+
echo "### 📊 Generation Statistics:" >> $GITHUB_STEP_SUMMARY
182+
echo "- **File Size**: $(numfmt --to=iec-i --suffix=B $FILE_SIZE)" >> $GITHUB_STEP_SUMMARY
183+
echo "- **Word Count**: $WORD_COUNT words" >> $GITHUB_STEP_SUMMARY
184+
echo "- **Rust Toolchain**: ${{ inputs.rust-nightly-version || 'nightly-2025-06-17' }}" >> $GITHUB_STEP_SUMMARY
185+
echo "" >> $GITHUB_STEP_SUMMARY
186+
fi
187+
188+
echo "### 📄 Generated Files:" >> $GITHUB_STEP_SUMMARY
189+
echo "- \`node-parameters.md\` - Complete configuration documentation" >> $GITHUB_STEP_SUMMARY
190+
echo "" >> $GITHUB_STEP_SUMMARY
191+
echo "### 📦 Artifact Details:" >> $GITHUB_STEP_SUMMARY
192+
echo "- **Name**: \`node-parameters.md\`" >> $GITHUB_STEP_SUMMARY
193+
echo "- **Retention**: 30 days" >> $GITHUB_STEP_SUMMARY
194+
echo "- **Location**: Available in workflow run artifacts section" >> $GITHUB_STEP_SUMMARY
195+
echo "" >> $GITHUB_STEP_SUMMARY
196+
echo "> 💡 **Tip**: Download the artifact to access the generated documentation files"

‎.github/workflows/stacks-core-tests.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,12 @@ jobs:
6868
input: ./docs/rpc/openapi.yaml
6969
output: ./open-api-docs.html
7070

71+
## Generate and upload node configuration documentation
72+
node-config-docsgen:
73+
name: Node Configuration Documentation
74+
needs: open-api-validation
75+
uses: ./.github/workflows/node-config-docsgen.yml
76+
7177
## Disabled
7278
## - this test can take several hours to run
7379
nettest:
@@ -138,6 +144,7 @@ jobs:
138144
if: always()
139145
needs:
140146
- open-api-validation
147+
- node-config-docsgen
141148
- core-contracts-clarinet-test
142149
steps:
143150
- name: Check Tests Status

0 commit comments

Comments
 (0)