Merge pull request #6227 from Jiloc/feat/generate-config-docs-on-ci

feat: generate config docs on ci

Author: wileyj

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

@@ -71,6 +71,15 @@ jobs:
           validate: "true"
           redocly-version: "1.34"
 
+  ## Generate and upload node configuration documentation
+  node-config-docsgen:
+    name: Node Configuration Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate Node Configuration Documentation
+        id: node_config_docsgen
+        uses: stacks-network/actions/stacks-core/node-config-docsgen@main
+
   ## Disabled
   ##   - this test can take several hours to run
   nettest:
@@ -141,6 +150,7 @@ jobs:
     if: always()
     needs:
       - open-api-validation
+      - node-config-docsgen
       - core-contracts-clarinet-test
     steps:
       - name: Check Tests Status

contrib/tools/config-docs-generator/generate-config-docs.sh

@@ -12,7 +12,7 @@ NC='\033[0m' # No Color
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../../../" && pwd)}"
 CARGO_TARGET_DIR="${CARGO_TARGET_DIR:-$PROJECT_ROOT/target}"
-OUTPUT_DIR="${OUTPUT_DIR:-$CARGO_TARGET_DIR/generated-docs}"
+OUTPUT_FILE="${OUTPUT_FILE:-$CARGO_TARGET_DIR/generated-docs/node-parameters.md}"
 TEMP_DIR="${TEMP_DIR:-$CARGO_TARGET_DIR/doc-generation}"
 
 # Binary paths - allow override via environment
@@ -52,11 +52,17 @@ main() {
     log_info "Starting config documentation generation..."
 
     # Create necessary directories
-    mkdir -p "$OUTPUT_DIR"
+    mkdir -p "$(dirname "$OUTPUT_FILE")"
     mkdir -p "$TEMP_DIR"
 
     cd "$PROJECT_ROOT"
 
+    # Workaround for new nightly lint that breaks stacks-common build.
+    # Allow callers to override or extend, but default to allowing the lint so documentation generation
+    # stays green until codebase is updated.
+    # TODO: Remove this once codebase will be updated to use the new lifetime syntax.
+    export RUSTFLAGS="${RUSTFLAGS:-} -A mismatched-lifetime-syntaxes"
+
     # Step 1: Build the documentation generation tools
     if [[ "$SKIP_BUILD" != "true" ]]; then
         log_info "Building documentation generation tools..."
@@ -81,22 +87,21 @@ main() {
 
     # Step 3: Generate Markdown
     log_info "Generating Markdown documentation..."
-    MARKDOWN_OUTPUT="$OUTPUT_DIR/configuration-reference.md"
 
     # Call the command
-    "$GENERATE_MARKDOWN_BIN" --input "$EXTRACTED_JSON" --output "$MARKDOWN_OUTPUT" --template "$TEMPLATE_PATH" --section-name-mappings "$SECTION_MAPPINGS_PATH"
+    "$GENERATE_MARKDOWN_BIN" --input "$EXTRACTED_JSON" --output "$OUTPUT_FILE" --template "$TEMPLATE_PATH" --section-name-mappings "$SECTION_MAPPINGS_PATH"
 
     log_info "Documentation generation complete!"
     log_info "Generated files:"
-    log_info "  - Configuration reference: $MARKDOWN_OUTPUT"
+    log_info "  - Configuration reference: $OUTPUT_FILE"
     log_info "  - Intermediate JSON: $EXTRACTED_JSON"
 
     # Verify output
-    if [[ -f "$MARKDOWN_OUTPUT" ]]; then
-        WORD_COUNT=$(wc -w < "$MARKDOWN_OUTPUT")
+    if [[ -f "$OUTPUT_FILE" ]]; then
+        WORD_COUNT=$(wc -w < "$OUTPUT_FILE")
         log_info "Generated Markdown contains $WORD_COUNT words"
     else
-        log_error "Expected output file not found: $MARKDOWN_OUTPUT"
+        log_error "Expected output file not found: $OUTPUT_FILE"
         exit 1
     fi
 }
@@ -125,7 +130,7 @@ DESCRIPTION:
     Source file: stackslib/src/config/mod.rs
 
 OUTPUT:
-    docs/generated/configuration-reference.md
+    docs/generated/node-parameters.md
 
 EOF
 }