chore: add script to update Trin Book's cli page #1867

KolbyML · 2025-05-29T00:00:39Z

What was wrong?

We were manually updating our Trin Book's cli configs this has 2 issues

the book is often out of date for long periods of time
We manually need to do this tedious work

How was it fixed?

Reth has a script for this https://github.com/paradigmxyz/reth/blob/a505f4914780c9ec6d1ca4ae1182244b851b89a7/book/cli/help.rs so I took it and left a comment on the top of the file attributing them. We have done this in a lot of our CI code, I can probably name like 5 CI jobs which were taken from Reth/Lighthouse

I also add make pr, which contributors should run before making a PR, which runs all the recommended commands and updates the book

carver

I'm not doing a deep review of book/src/cli/help.rs, there's a lot there, but I guess you ran it already and the only difference was that temporary directory remapping, so that seems promising. I guess hopefully we would notice a bug pretty easily when the CLI output in the book changes in some weird way.

I don't love having a lot of functionality around that is unused or buggy, so I'm in favor of dropping a lot of stuff we don't need/use. More below

carver · 2025-05-29T22:25:28Z

book/src/cli/update.sh

+#!/usr/bin/env bash
+set -eo pipefail
+
+BOOK_ROOT="$(dirname "$(dirname "$0")")"


nit: I would expect book/ to be BOOK_ROOT. Since this is book/src/, maybe we could call it BOOK_SRC or BOOK_SRC_ROOT?

carver · 2025-05-29T22:28:35Z

book/src/SUMMARY.md

+    - [All Command Line Flags](cli/cli.md) <!-- CLI_REFERENCE START -->
+      - [`trin`](./cli/trin.md)


Not a huge deal, but I did find it pleasing to have everything under "Using trin" to be in the same (users/) folder. Maybe users/cli/trin.md?

carver · 2025-05-29T22:29:12Z

book/src/SUMMARY.md

-    - [All Command Line Flags](users/cli.md)
+    - [All Command Line Flags](cli/cli.md) <!-- CLI_REFERENCE START -->
+      - [`trin`](./cli/trin.md)
+    - [FAQ](users/faq.md) <!-- CLI_REFERENCE END -->


It's confusing/weird to me that the CLI_REFERENCE END comes after the faq that is not a CLI reference.

carver · 2025-05-29T22:30:42Z

book/src/cli/help.rs

@@ -0,0 +1,383 @@
+#!/usr/bin/env -S cargo +nightly -Zscript
+
+# This script generates cli.


Suggested change

# This script generates cli.

# This is a CLI tool to gather `--help` output from other CLI tools.

carver · 2025-05-29T22:32:44Z

book/src/cli/trin.md

@@ -28,7 +22,7 @@ Options:
      --web3-ipc-path <WEB3_IPC_PATH>
          path to json-rpc endpoint over IPC

-          [default: /tmp/trin-jsonrpc.ipc]
+          [default: <CACHE_DIR>-jsonrpc.ipc]


carver · 2025-05-29T22:51:16Z

book/src/cli/help.rs

+            // Remove rpc.max-tracing-requests default value
+            (
+                r"(rpc.max-tracing-requests <COUNT>\n.*\n.*\n.*\n.*\n.*)\[default: \d+\]",
+                r"$1[default: <NUM CPU CORES-2>]",
+            ),


Looks like we can remove this as irrelevant to us.

carver · 2025-05-29T22:56:15Z

book/src/cli/help.rs

+            // Remove the commit SHA and target architecture triple or fourth
+            //  rustup available targets:
+            //    aarch64-apple-darwin
+            //    x86_64-unknown-linux-gnu
+            //    x86_64-pc-windows-gnu
+            (
+                r"default: trin/.*-[0-9A-Fa-f]{6,10}/([_\w]+)-(\w+)-(\w+)(-\w+)?",
+                "default: trin/<VERSION>-<SHA>/<ARCH>",
+            ),
+            // Remove the OS
+            (r"default: trin/.*/\w+", "default: trin/<VERSION>/<OS>"),


So neither of these are currently in action. My preference would be to remove them and leave a comment reminding future us that we can find more patterns in the reth source linked at the top of the file.

But if you really want to keep them in, then I guess at least it would be good to have a comment like: we know that these patterns are inactive; they are meant to be examples for future usage.

carver · 2025-05-29T23:04:40Z

book/src/cli/help.rs

+    // Generate README.md.
+    if args.readme {
+        let path = &out_dir.join("README.md");
+        if args.verbose {
+            println!("Writing README.md to \"{}\"", path.to_string_lossy());
+        }
+        write_file(path, README)?;
+    }
+


I'd say we should generally remove stuff we're not using, like this, README and the readme flag for this tool.

carver · 2025-05-29T23:14:10Z

book/src/cli/help.rs

+    let section_re = regex!(&format!(r"(?s)\s*{SECTION_START}.*?{SECTION_END}"));
+    if !section_re.is_match(&original_summary_content) {
+        eprintln!(
+            "Could not find CLI_REFERENCE section in {}. Please add the following section to the file:\n{}\n... CLI Reference goes here ...\n\n{}",
+            summary_file.display(),
+            SECTION_START,
+            SECTION_END
+        );
+        process::exit(1);
+    }
+
+    let section_end_re = regex!(&format!(r".*{SECTION_END}"));
+    let last_line = section_end_re
+        .find(&original_summary_content)
+        .map(|m| m.as_str().to_string())
+        .expect("Could not extract last line of CLI_REFERENCE section");


This whole thing feels pretty hacky. Maybe that's okay for a quick tool, but I think we can avoid all of it by just naming the tool list something different than ...cli/SUMMARY.md, like cli/all_binaries.md. Then we can just parse the whole file looking for the page of that name, and drop the hacky tag markings altogether.

carver · 2025-05-29T23:16:42Z

book/src/SUMMARY.md

@@ -11,8 +11,9 @@
    - [Requirements](users/requirements.md)
    - [Monitoring](users/monitoring.md)
    - [Problems](users/problems.md)
-    - [FAQ](users/faq.md)
-    - [All Command Line Flags](users/cli.md)
+    - [All Command Line Flags](cli/cli.md) <!-- CLI_REFERENCE START -->


I think we can come closer to the semantic meaning than cli/cli.md. If it stays in the users/ folder, maybe: users/cli/tool_index.md since it links out to the help output for a (theoretical) list of tools.

chore: add script to update Trin Book's cli page

c92d17f

KolbyML requested review from carver and morph-dev May 29, 2025 00:00

KolbyML self-assigned this May 29, 2025

carver reviewed May 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: add script to update Trin Book's cli page #1867

chore: add script to update Trin Book's cli page #1867

Uh oh!

KolbyML commented May 29, 2025

Uh oh!

carver left a comment

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

carver May 29, 2025

Uh oh!

Uh oh!

		- [All Command Line Flags](cli/cli.md) <!-- CLI_REFERENCE START -->
		- [`trin`](./cli/trin.md)

		@@ -0,0 +1,383 @@
		#!/usr/bin/env -S cargo +nightly -Zscript

		# This script generates cli.

	# This script generates cli.
	# This is a CLI tool to gather `--help` output from other CLI tools.

chore: add script to update Trin Book's cli page #1867

Are you sure you want to change the base?

chore: add script to update Trin Book's cli page #1867

Uh oh!

Conversation

KolbyML commented May 29, 2025

What was wrong?

How was it fixed?

Uh oh!

carver left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!