Merge pull request #8 from tcharding/06-17-docs

regtest: Try to fix docs

Author: tcharding

Cargo-minimal.lock

@@ -86,7 +86,7 @@ dependencies = [
 
 [[package]]
 name = "bitcoind-json-rpc-client"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "bitcoin",
  "bitcoind-json-rpc-types",

Cargo-recent.lock

@@ -86,7 +86,7 @@ dependencies = [
 
 [[package]]
 name = "bitcoind-json-rpc-client"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "bitcoin",
  "bitcoind-json-rpc-types",

regtest/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.2.1 - 2024-06-17
+
+Do various little fixes to try and make the docs on `Client` more legible, specifically to alleviate
+confusion around the flag on `docs.rs` that says "Available on crate feature 26_0 only."
+
 # 0.2.0 - 2024-06-13
 
 - Use Bitcoin Core 0.17.1 (0.17.2 seems to not exist and have been a mistake).

regtest/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bitcoind-json-rpc-regtest"
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Riccardo Casatta <[email protected]>", "Tobin C. Harding <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/tcharding/rust-bitcoind-json-rpc"
@@ -65,7 +65,7 @@ anyhow = "1.0.66"
 
 
 [package.metadata.docs.rs]
-features = ["download", "doc"]
+features = ["download", "doc", "26_0"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [patch.crates-io.bitcoind-json-rpc-client]

regtest/README.md

@@ -1,7 +1,3 @@
-[![MIT license](https://img.shields.io/github/license/RCasatta/bitcoind)](https://github.com/RCasatta/bitcoind/blob/master/LICENSE)
-[![Crates](https://img.shields.io/crates/v/bitcoind.svg)](https://crates.io/crates/bitcoind)
-[![Docs](https://img.shields.io/badge/docs.rs-bitcoind-green)](https://docs.rs/bitcoind)
-
 # Bitcoind
 
 Utility to run a regtest bitcoind process, useful in integration testing environment.
@@ -19,8 +15,7 @@ for bitcoin core 25.1, starting a regtest node is as simple as that:
 ```
 
 The build script will automatically download the bitcoin core version 25.1 from [bitcoin core](https://bitcoincore.org),
-verify the hashes and place it in the build directory for this crate. If you wish to download from an 
-alternate location, for example locally for CI, use the `BITCOIND_DOWNLOAD_ENDPOINT` env var.
+verify the binary hash and place it in the build directory for this crate.
 
 When you don't use the auto-download feature you have the following options:
 
@@ -37,22 +32,15 @@ if let Ok(exe_path) = bitcoind::exe_path() {
 Startup options could be configured via the [`Conf`] struct using [`BitcoinD::with_conf`] or 
 [`BitcoinD::from_downloaded_with_conf`]
 
-## Issues with traditional approach
-
-I used integration testing based on external bash script launching needed external processes, there 
-are many issues with this approach like:
-
-* External script may interfere with local development environment [1](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/run.sh#L9)
-* Use of a single huge test to test everything [2](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/src/main.rs#L122-L203)
-* If test are separated, a failing test may fail to leave a clean situation, causing other test to fail (because of the initial situation, not a real failure)
-* bash script are hard, especially support different OS and versions
-
 ## Features
 
-  * It waits until bitcoind daemon become ready to accept RPC commands
-  * `bitcoind` use a temporary directory as datadir. You can specify the root of your temp directories so that you have node's datadir in a RAM disk (eg `/dev/shm`)
-  * Free ports are asked to the OS. Since you can't reserve the given port, a low probability race condition is still possible, for this reason the process is tried to be spawn 3 times with different ports.
-  * The process is killed when the struct goes out of scope no matter how the test finishes
+  * Waits until bitcoind daemon becomes ready to accept RPC commands
+  * `bitcoind` uses a temporary directory as datadir. You can specify the root of your temp
+    directories so that you have the node's datadir in a RAM disk (eg `/dev/shm`)
+  * Free ports are requested from the OS. Since you can't reserve the given port, a low probability
+    race condition is still possible, for this reason the process attempts spawning 3 times with
+    different ports.
+  * The process is killed when the struct goes out of scope no matter how the test finishes.
   * Allows easy spawning of dependent processes like:
     - [electrs](https://github.com/RCasatta/electrsd)
     - [cln](https://github.com/RCasatta/lightningd)
@@ -85,28 +73,11 @@ Pinning in `Cargo.toml` is avoided because it could cause compilation issues dow
 
 ## Nix
 
-For reproducibility reasons, Nix build scripts cannot hit the internet, but the
-auto-download feature does exactly that. To successfully build under Nix the
-user must provide the tarball locally and specify its location via the
-`BITCOIND_TARBALL_FILE` env var.
-
-Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the
-executable via the `PATH`.
-
-Alternatively, use the dep without auto-download feature.
-
-## Used by
-
-* [firma](https://github.com/RCasatta/firma/)
-* [payjoin](https://github.com/Kixunil/payjoin)
-* [rust-miniscript](https://github.com/rust-bitcoin/rust-miniscript/tree/4a3ba11c2fd5063be960741d557f3f7a28041e1f/bitcoind-tests)
-
-### Via bdk dependency
-
-* [gun](https://github.com/LLFourn/gun)
+For reproducibility reasons, Nix build scripts cannot hit the internet, but the auto-download
+feature does exactly that. To successfully build under Nix the user must provide the tarball locally
+and specify its location via the `BITCOIND_TARBALL_FILE` env var.
 
-### Via electrsd dependency:
+Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the executable via the
+`PATH`.
 
-* [bdk](https://github.com/bitcoindevkit/bdk)
-* [BEWallet](https://github.com/LeoComandini/BEWallet)
-* [gdk rust](https://github.com/Blockstream/gdk/blob/master/subprojects/gdk_rust/)
+Alternatively, use the dep without the auto-download feature.

regtest/src/client_versions.rs

@@ -1,4 +1,10 @@
 // All features uses 26_0
+/// The version specific client and json types.
+///
+/// **THIS IS AVAILABLE FOR ALL VERSION NUMBER FEATURES** (eg `25_0`, `24_2` etc). This crate is
+/// unusual in that it expects exactly one version number feature to be selected, docs.rs is not set
+/// up to handle such oddity.
+///
 #[cfg(feature = "26_0")]
 #[allow(unused_imports)] // Not all users need the json types.
 pub use bitcoind_json_rpc_client::{client_sync::v26::{Client, AddressType}, json::v26 as json};
@@ -67,7 +73,7 @@ pub use bitcoind_json_rpc_client::{client_sync::v18::{Client, AddressType}, json
 #[allow(unused_imports)] // Not all users need the json types.
 pub use bitcoind_json_rpc_client::{client_sync::v17::{Client, AddressType}, json::v17 as json};
 
-// To make --no-default-features work we have to enable some feature, use most recent version same as for default.
-#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feadure = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))]
+// To make --no-default-features work we have to re-export a the types, use most recent version same as we do for all features.
+#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feature = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))]
 #[allow(unused_imports)] // Not all users need the json types.
 pub use bitcoind_json_rpc_client::{client_sync::v26::{Client, AddressType}, json::v26 as json};

regtest/src/lib.rs

@@ -21,6 +21,7 @@ use tempfile::TempDir;
 pub use {anyhow, tempfile, which};
 
 #[rustfmt::skip]                // Keep pubic re-exports separate.
+#[doc(inline)]
 pub use self::{
     client_versions::{json, Client, AddressType},
     versions::VERSION,

regtest/src/versions.rs

@@ -50,6 +50,6 @@ pub const VERSION: &str = "0.18.1";
 pub const VERSION: &str = "0.17.1";
 
 // To make --no-default-features work we have to enable some feature, use most recent version same as for default.
-#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feadure = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))]
+#[cfg(all(not(feature = "26_0"), not(feature = "25_2"), not(feature = "25_1"), not(feature = "25_0"), not(feature = "24_2"),not(feature = "24_1"), not(feature = "24_0_1"), not(feature = "23_2"), not(feature = "23_1"), not(feature = "23_0"), not(feature = "22_1"), not(feature = "22_0"), not(feature = "0_21_2"), not(feature = "0_20_2"), not(feature = "0_19_1"), not(feature = "0_18_1"), not(feature = "0_17_1")))]
 #[allow(dead_code)]         // for --no-default-features
 pub const VERSION: &str = "26.0";