use mapping file for TARGET_STRUCTS

Author: Jiloc

contrib/tools/config-docs-generator/Dockerfile

@@ -1,6 +1,11 @@
 # Use a specific nightly toolchain for reproducible builds
 FROM rustlang/rust@sha256:04690ffa09cddd358b349272173155319f384e57816614eea0840ec7f9422862
 
+RUN apt-get update -y \
+ && apt-get install -y --no-install-recommends \
+    jq \
+ && rm -rf /var/lib/apt/lists/*
+
 # Set the working directory for building
 WORKDIR /build
 
@@ -15,12 +20,12 @@ RUN cargo build --package config-docs-generator --release
 WORKDIR /project_root
 
 # Set environment variables for generate-config-docs.sh
-ENV PROJECT_ROOT=/project_root
-ENV CARGO_TARGET_DIR=/tmp/stacks-config-docs/target
-ENV TEMP_DIR=/tmp/stacks-config-docs/doc-generation
-ENV EXTRACT_DOCS_BIN=/build/target/release/extract-docs
-ENV GENERATE_MARKDOWN_BIN=/build/target/release/generate-markdown
-ENV SKIP_BUILD=true
+ENV PROJECT_ROOT=/project_root \
+    CARGO_TARGET_DIR=/tmp/stacks-config-docs/target \
+    TEMP_DIR=/tmp/stacks-config-docs/doc-generation \
+    EXTRACT_DOCS_BIN=/build/target/release/extract-docs \
+    GENERATE_MARKDOWN_BIN=/build/target/release/generate-markdown \
+    SKIP_BUILD=true
 
 # Create the Docker-specific temp directory
 RUN mkdir -p /tmp/stacks-config-docs

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

@@ -66,10 +66,14 @@ main() {
     # Step 2: Extract documentation from source code using rustdoc
     log_info "Extracting configuration documentation using rustdoc..."
     EXTRACTED_JSON="$TEMP_DIR/extracted-config-docs.json"
-    # List of specific Rust struct names to be documented
-    # NOTE: This variable must be manually updated if this list changes
-    # (e.g., new config structs are added or removed from the project)
-    TARGET_STRUCTS="BurnchainConfig,NodeConfig,MinerConfig,ConnectionOptionsFile,FeeEstimationConfigFile,EventObserverConfigFile,InitialBalanceFile"
+
+    # Determine the list of structs to document from section_name_mappings.json
+    # If the caller sets $TARGET_STRUCTS explicitly we honour that override.
+    if [[ -z "${TARGET_STRUCTS:-}" ]]; then
+        TARGET_STRUCTS="$(jq -r 'keys | join(",")' "$SECTION_MAPPINGS_PATH")"
+    fi
+    log_info "Structs to be documented: $TARGET_STRUCTS"
+
     "$EXTRACT_DOCS_BIN" \
         --package stackslib \
         --structs "$TARGET_STRUCTS" \

docs/generated/configuration-reference.md

@@ -106,7 +106,7 @@ The configuration is automatically generated from the Rust source code documenta
 | [<span id="burnchain-block_commit_tx_estimated_size">block_commit_tx_estimated_size</span>](#burnchain-block_commit_tx_estimated_size) | Estimated size (in virtual bytes) of a block commit transaction on bitcoin.<br>Used for fee calculation in mining logic by multiplying with the fee rate<br>[satoshis_per_byte](#burnchain-satoshis_per_byte) .<br><br>**Notes:**<br>- Only relevant if [[node].miner](#node-miner)  is `true`.<br><br>**Units:** virtual bytes | `380` |
 | [<span id="burnchain-burn_fee_cap">burn_fee_cap</span>](#burnchain-burn_fee_cap) | The maximum amount (in sats) of "burn commitment" to broadcast for the next<br>block's leader election. Acts as a safety cap to limit the maximum amount<br>spent on mining. It serves as both the target fee and a fallback if dynamic<br>fee calculations fail or cannot be performed.<br><br>This setting can be hot-reloaded from the config file, allowing adjustment<br>without restarting.<br><br>**Notes:**<br>- Only relevant if [[node].miner](#node-miner)  is `true`.<br><br>**Units:** satoshis | `20_000` |
 | [<span id="burnchain-chain">chain</span>](#burnchain-chain) | The underlying blockchain used for Proof-of-Transfer.<br><br>**Notes:**<br>- Currently, only `"bitcoin"` is supported. | `"bitcoin"` |
-| [<span id="burnchain-chain_id">chain_id</span>](#burnchain-chain_id) | The network-specific identifier used in P2P communication and database initialization.<br><br>**Notes:**<br>- **Warning:** Do not modify this unless you really know what you're doing.<br>- This is intended strictly for testing purposes. | - if [mode](#burnchain-mode)  is `"mainnet"`: `CHAIN_ID_MAINNET`<br>- else: `CHAIN_ID_TESTNET` |
+| [<span id="burnchain-chain_id">chain_id</span>](#burnchain-chain_id) | The network-specific identifier used in P2P communication and database initialization.<br><br>**Notes:**<br>- **Warning:** Do not modify this unless you really know what you're doing.<br>- This is intended strictly for testing purposes. | - if [mode](#burnchain-mode)  is `"mainnet"`: `0x00000001`<br>- else: `0x80000000` |
 | [<span id="burnchain-commit_anchor_block_within">commit_anchor_block_within</span>](#burnchain-commit_anchor_block_within) | Specifies a mandatory wait period (in milliseconds) after receiving a burnchain tip<br>before the node attempts to build the anchored block for the new tenure.<br>This duration effectively schedules the start of the block-building process<br>relative to the tip's arrival time.<br><br>**Notes:**<br>- This is intended strictly for testing purposes.<br><br>**Units:** milliseconds | `5_000` |
 | [<span id="burnchain-epochs">epochs</span>](#burnchain-epochs) | Custom override for the definitions of Stacks epochs (start/end burnchain<br>heights, consensus rules). This setting allows testing specific epoch<br>transitions or custom consensus rules by defining exactly when each epoch<br>starts on bitcoin.<br><br>Epochs define distinct protocol rule sets (consensus rules, execution costs,<br>capabilities). When configured, the list must include all epochs<br>sequentially from "1.0" up to the highest desired epoch, without skipping<br>any intermediate ones. Valid `epoch_name` values currently include:<br>`"1.0"`, `"2.0"`, `"2.05"`, `"2.1"`, `"2.2"`, `"2.3"`, `"2.4"`, `"2.5"`, `"3.0"`, `"3.1"`.<br><br>**Validation Rules:**<br>- Epochs must be provided in strict chronological order (`1.0`, `2.0`, `2.05`...).<br>- `start_height` values must be non-decreasing across the list.<br>- Epoch `"1.0"` must have `start_height = 0`.<br>- The number of defined epochs cannot exceed the maximum supported by the node software.<br><br>**Notes:**<br>- Applied only if [mode](#burnchain-mode)  is not "mainnet".<br>- This is intended strictly for testing purposes.<br>- Configured as a list `[[burnchain.epochs]]` in TOML, each with `epoch_name` (string) and `start_height` (integer Bitcoin block height).<br><br>**Example:**<br><pre><code>[[burnchain.epochs]]&#10;epoch_name = "2.1"&#10;start_height = 150&#10;&#10;[[burnchain.epochs]]&#10;epoch_name = "2.2"&#10;start_height = 200</code></pre> | `None` (uses the standard epoch definitions for the selected [mode](#burnchain-mode) ) |
 | [<span id="burnchain-fault_injection_burnchain_block_delay">fault_injection_burnchain_block_delay</span>](#burnchain-fault_injection_burnchain_block_delay) | Fault injection setting for testing. Introduces an artificial delay (in<br>milliseconds) before processing each burnchain block download. Simulates a<br>slow burnchain connection.<br><br>**Notes:**<br>- This is intended strictly for testing purposes.<br><br>**Units:** milliseconds | `0` (no delay) |
@@ -122,7 +122,7 @@ The configuration is automatically generated from the Rust source code documenta
 | [<span id="burnchain-password">password</span>](#burnchain-password) | The password for authenticating with the bitcoin node's RPC interface.<br>Required if the bitcoin node requires RPC authentication.<br><br>**Notes:**<br>- Only relevant if [[node].miner](#node-miner)  is `true`. | `None` |
 | [<span id="burnchain-peer_host">peer_host</span>](#burnchain-peer_host) | The hostname or IP address of the bitcoin node peer.<br><br>This field is required for all node configurations as it specifies where to<br>find the underlying bitcoin node to interact with for PoX operations,<br>block validation, and mining. | `"0.0.0.0"` |
 | [<span id="burnchain-peer_port">peer_port</span>](#burnchain-peer_port) | The P2P network port of the bitcoin node specified by [peer_host](#burnchain-peer_host) . | `8333` |
-| [<span id="burnchain-peer_version">peer_version</span>](#burnchain-peer_version) | The peer protocol version number used in P2P communication.<br>This parameter cannot be set via the configuration file.<br><br>**Notes:**<br>- **Warning:** Do not modify this unless you really know what you're doing. | - if [mode](#burnchain-mode)  is `"mainnet"`: `PEER_VERSION_MAINNET`<br>- else: `PEER_VERSION_TESTNET` |
+| [<span id="burnchain-peer_version">peer_version</span>](#burnchain-peer_version) | The peer protocol version number used in P2P communication.<br>This parameter cannot be set via the configuration file.<br><br>**Notes:**<br>- **Warning:** Do not modify this unless you really know what you're doing. | - if [mode](#burnchain-mode)  is `"mainnet"`: `402_653_196`<br>- else: `4_207_599_116` |
 | [<span id="burnchain-poll_time_secs">poll_time_secs</span>](#burnchain-poll_time_secs) | The interval, in seconds, at which the node polls the bitcoin node for new<br>blocks and state updates.<br><br>The default value of 10 seconds is mainly intended for testing purposes.<br>It's suggested to set this to a higher value for mainnet, e.g., 300 seconds<br>(5 minutes).<br><br>**Units:** seconds | `10` |
 | [<span id="burnchain-pox_2_activation">pox_2_activation</span>](#burnchain-pox_2_activation) | Sets a custom burnchain height for PoX-2 activation (for testing).<br><br>This affects two key transitions:<br>1. The block height at which PoX v1 lockups are automatically unlocked.<br>2. The block height from which PoX reward set calculations switch to PoX v2 rules.<br><br>**Behavior:**<br>- This value directly sets the auto unlock height for PoX v1 lockups before<br>  transition to PoX v2. This also defines the burn height at which PoX reward<br>  sets are calculated using PoX v2 rather than v1.<br>- If custom [epochs](#burnchain-epochs)  are provided:<br>&nbsp;&nbsp;- This value is used to validate that Epoch 2.1's start height is ≤ this value.<br>&nbsp;&nbsp;- However, the height specified in `epochs` for Epoch 2.1 takes precedence.<br><br>**Notes:**<br>- Applied only if [mode](#burnchain-mode)  is not "mainnet".<br>- This is intended strictly for testing purposes. | `None` |
 | [<span id="burnchain-pox_prepare_length">pox_prepare_length</span>](#burnchain-pox_prepare_length) | Overrides the length (in bitcoin blocks) of the PoX prepare phase.<br><br>**Notes:**<br>- Applied only if [mode](#burnchain-mode)  is not "mainnet".<br>- This is intended strictly for testing purposes.<br><br>**Units:** bitcoin blocks | `None` (uses the standard prepare phase length for the mode) |