fix(doc): Fix broken links to zebra_network and zebra_state `Conf…

…ig` structs on doc.zebra.zfnd.org (#7838)

* Use full module paths to avoid a rustdoc bug

* Exclude zebra-test from external docs

.github/workflows/docs-deploy-firebase.yml

@@ -144,8 +144,8 @@ jobs:
 
       - name: Build external docs
         run: |
-          # Exclude zebra-utils, it is not for library or app users
-          cargo doc --no-deps --workspace --all-features --exclude zebra-utils --target-dir "$(pwd)"/target/external
+          # Exclude zebra-utils and zebra-test, they are not for library or app users
+          cargo doc --no-deps --workspace --all-features --exclude zebra-utils --exclude zebra-test --target-dir "$(pwd)"/target/external
 
       # Setup gcloud CLI
       - name: Authenticate to Google Cloud

zebra-consensus/src/lib.rs

@@ -46,11 +46,11 @@
 
 mod block;
 mod checkpoint;
-mod config;
 mod parameters;
 mod primitives;
 mod script;
 
+pub mod config;
 pub mod error;
 pub mod router;
 pub mod transaction;

zebra-network/src/lib.rs

@@ -159,11 +159,12 @@ extern crate bitflags;
 /// parameterized by 'a), *not* that the object itself has 'static lifetime.
 pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
 
-mod address_book;
 pub mod address_book_peers;
-mod address_book_updater;
-mod config;
+pub mod config;
 pub mod constants;
+
+mod address_book;
+mod address_book_updater;
 mod isolated;
 mod meta_addr;
 mod peer;

zebra-state/src/config.rs

@@ -385,44 +385,52 @@ pub(crate) fn database_format_version_at_path(
     }
 }
 
-/// Writes `changed_version` to the on-disk database after the format is changed.
-/// (Or a new database is created.)
-///
-/// # Correctness
-///
-/// This should only be called:
-/// - after each format upgrade is complete,
-/// - when creating a new database, or
-/// - when an older Zebra version opens a newer database.
-///
-/// # Concurrency
-///
-/// This must only be called while RocksDB has an open database for `config`.
-/// Otherwise, multiple Zebra processes could write the version at the same time,
-/// corrupting the file.
-///
-/// # Panics
-///
-/// If the major versions do not match. (The format is incompatible.)
-pub fn write_database_format_version_to_disk(
-    changed_version: &Version,
-    config: &Config,
-    network: Network,
-) -> Result<(), BoxError> {
-    let version_path = config.version_file_path(network);
+// Hide this destructive method from the public API, except in tests.
+pub(crate) use hidden::write_database_format_version_to_disk;
 
-    // The major version is already in the directory path.
-    assert_eq!(
-        changed_version.major, DATABASE_FORMAT_VERSION,
-        "tried to do in-place database format change to an incompatible version"
-    );
+pub(crate) mod hidden {
 
-    let version = format!("{}.{}", changed_version.minor, changed_version.patch);
+    use super::*;
 
-    // # Concurrency
-    //
-    // The caller handles locking for this file write.
-    fs::write(version_path, version.as_bytes())?;
+    /// Writes `changed_version` to the on-disk database after the format is changed.
+    /// (Or a new database is created.)
+    ///
+    /// # Correctness
+    ///
+    /// This should only be called:
+    /// - after each format upgrade is complete,
+    /// - when creating a new database, or
+    /// - when an older Zebra version opens a newer database.
+    ///
+    /// # Concurrency
+    ///
+    /// This must only be called while RocksDB has an open database for `config`.
+    /// Otherwise, multiple Zebra processes could write the version at the same time,
+    /// corrupting the file.
+    ///
+    /// # Panics
+    ///
+    /// If the major versions do not match. (The format is incompatible.)
+    pub fn write_database_format_version_to_disk(
+        changed_version: &Version,
+        config: &Config,
+        network: Network,
+    ) -> Result<(), BoxError> {
+        let version_path = config.version_file_path(network);
+
+        // The major version is already in the directory path.
+        assert_eq!(
+            changed_version.major, DATABASE_FORMAT_VERSION,
+            "tried to do in-place database format change to an incompatible version"
+        );
+
+        let version = format!("{}.{}", changed_version.minor, changed_version.patch);
 
-    Ok(())
+        // # Concurrency
+        //
+        // The caller handles locking for this file write.
+        fs::write(version_path, version.as_bytes())?;
+
+        Ok(())
+    }
 }

zebra-state/src/lib.rs

@@ -25,12 +25,12 @@
 #[macro_use]
 extern crate tracing;
 
+pub mod config;
 pub mod constants;
 
 #[cfg(any(test, feature = "proptest-impl"))]
 pub mod arbitrary;
 
-mod config;
 mod error;
 mod request;
 mod response;
@@ -71,7 +71,7 @@ pub use service::{
 };
 
 #[cfg(any(test, feature = "proptest-impl"))]
-pub use config::write_database_format_version_to_disk;
+pub use config::hidden::write_database_format_version_to_disk;
 
 #[cfg(any(test, feature = "proptest-impl"))]
 pub use constants::latest_version_for_adding_subtrees;

zebrad/src/config.rs

@@ -15,16 +15,18 @@ use serde::{Deserialize, Serialize};
 #[serde(deny_unknown_fields, default)]
 pub struct ZebradConfig {
     /// Consensus configuration
-    pub consensus: zebra_consensus::Config,
+    //
+    // These configs use full paths to avoid a rustdoc link bug (#7048).
+    pub consensus: zebra_consensus::config::Config,
 
     /// Metrics configuration
     pub metrics: crate::components::metrics::Config,
 
     /// Networking configuration
-    pub network: zebra_network::Config,
+    pub network: zebra_network::config::Config,
 
     /// State configuration
-    pub state: zebra_state::Config,
+    pub state: zebra_state::config::Config,
 
     /// Tracing configuration
     pub tracing: crate::components::tracing::Config,