chore: fix documentation CLI (#6566)

* chore: fix documentation CLI * chore: lint md files * chore: do not run spellcheck on generated CLI md * chore: address comments * chore: address comments * chore: escape titles * chore: generate TOC * chore: address comments * chore: fix lint * Revert "chore: generate TOC" This reverts commit 652422a. * chore: remove custom ids and move down header
ChainSafe · Mar 25, 2024 · 948de61 · 948de61
1 parent 533a08e
commit 948de61
Show file tree

Hide file tree

Showing 9 changed files with 31 additions and 20 deletions.
diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml
@@ -41,10 +41,9 @@ jobs:
       - name: Build and collect docs
         run: yarn docs:build
 
-      # Run prettier check with fix after generating the docs. The CLI reference is formatted with prettier for
-      # deployed version so this will fail if not "fixable"
+      # Run prettier check after generating the docs
       - name: Check docs format
-        run: yarn docs:lint:fix
+        run: yarn docs:lint
 
       # Run spellcheck AFTER building docs, in case the CLI reference has issues
       - name: Spellcheck

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ Contributing to tests:
 
 **Error: [vitest] Cannot mock "../../src/db/repositories/index.js" because it is already loaded by "src/db/beacon.ts"**
 
-If you observe any error in tests with matching to above error message, that implies you are loading the mocks in the wrong order. The correct order is to import the mocks first and then the actual module. We suggest to import the mocks on very top before any local modules. 
+If you observe any error in tests with matching to above error message, that implies you are loading the mocks in the wrong order. The correct order is to import the mocks first and then the actual module. We suggest to import the mocks on very top before any local modules.
 
 **✖ Error: Cannot find package 'async_hooks' imported from**
 

diff --git a/README.md b/README.md
@@ -46,7 +46,7 @@ yarn build
 
 | Package                                                     | Version                                                                                                                     | License                                                                                                               | Docs                                                                                      | Description                                                      |
 | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| [`@lodestar/beacon-node`](./packages/beacon-node)           | [![npm](https://img.shields.io/npm/v/@lodestar/beacon-node)](https://www.npmjs.com/package/@lodestar/beacon-node)               | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/beacon-node)      | :rotating_light: Beacon-chain client                             |
+| [`@lodestar/beacon-node`](./packages/beacon-node)           | [![npm](https://img.shields.io/npm/v/@lodestar/beacon-node)](https://www.npmjs.com/package/@lodestar/beacon-node)           | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/beacon-node)      | :rotating_light: Beacon-chain client                             |
 | [`@lodestar/validator`](./packages/validator)               | [![npm](https://img.shields.io/npm/v/@lodestar/validator)](https://www.npmjs.com/package/@lodestar/validator)               | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/validator)        | :bank: Validator client                                          |
 | [`@lodestar/light-client`](./packages/light-client)         | [![npm](https://img.shields.io/npm/v/@lodestar/light-client)](https://www.npmjs.com/package/@lodestar/light-client)         | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)  | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/light-client)     | :bird: Ethereum Light client                                     |
 | [`@lodestar/api`](./packages/api)                           | [![npm](https://img.shields.io/npm/v/@lodestar/api)](https://www.npmjs.com/package/@lodestar/api)                           | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)  | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/api)              | :clipboard: REST Client for the Ethereum Beacon API              |

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -105,6 +105,10 @@ const config: Config = {
       theme: prismThemes.vsLight,
       darkTheme: prismThemes.vsDark,
     },
+    tableOfContents: {
+      minHeadingLevel: 2,
+      maxHeadingLevel: 5,
+    },
   } satisfies Preset.ThemeConfig,
 };
 

diff --git a/docs/pages/faqs.md b/docs/pages/faqs.md
@@ -9,10 +9,12 @@ This section of the documentation will cover common questions and encounters oft
 :::note "Unknown arguments error"
 Lodestar reads all environment variables prefixed with `LODESTAR` and will try to parse
 them similar to command line arguments, meaning any unknown argument will cause an error.
+
 ```
 ✖ Unknown arguments: servicePort, servicePortEthConsensusP2p,
 port9000Tcp, port9000TcpPort, port9000TcpProto, port9000TcpAddr, serviceHost
 ```
+
 The extra arguments are present because Kubernetes automatically
 [adds environment variables](https://kubernetes.io/docs/concepts/services-networking/service/#environment-variables)
 to the Pod based on the name (`metadata.name`) defined in the associated `Service`.

diff --git a/docs/pages/logging-and-metrics/client-monitoring.md b/docs/pages/logging-and-metrics/client-monitoring.md
@@ -29,6 +29,7 @@ When sending data to a remote service you should be conscious about security:
   and associate your validators, IP address and other personal information.
 - Always use a HTTPS connection (i.e. a URL starting with `https://`) to prevent the traffic
   from being intercepted in transit and leaking information.
+
 :::
 
 More details about the data sent to the remote service can be found in the [specification](https://docs.google.com/document/d/1qPWAVRjPCENlyAjUBwGkHMvz9qLdd_6u9DPZcNxDBpc).

diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md
@@ -47,7 +47,7 @@ _Plaintext passphrase file import_
 :::info
 The interactive passphrase import method will prompt every keystore in the `validator_keys` folder for import and will ask for the individual password for each keystore. **This method will allow you to import multiple keystores with different passwords.**
 
-The plaintext passphrase file import method will allow you to import all keystores in the `validator_keys` folder encrypted with the same password contained in `password.txt` for efficiency. 
+The plaintext passphrase file import method will allow you to import all keystores in the `validator_keys` folder encrypted with the same password contained in `password.txt` for efficiency.
 :::
 
 Once imported with either method, these keystores will be automatically loaded when you start the validator. To list the imported keystores, use the `validator list` command.
@@ -85,17 +85,19 @@ With Lodestar's `--builder.selection` validator options, you can select:
 - `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below.
 - `executionalways`: An alias of `--builder.boostFactor=0`, which will select the local execution block, unless it fails to produce due to an error or a delay in the response from the execution client.
 - `executiononly`: Beacon node will be requested to produce local execution block even if builder relays are configured. This option will always select the local execution block and will error if it couldn't produce one.
-- `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response.
+- `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2\*\*64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response.
 - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_.
 
 #### Calculating builder boost factor with examples
 
 To calculate the builder boost factor setting, you need to know what percentage you will accept a builder block for against a local execution block using the following formula: `100*100/(100+percentage)`. The value passed to `--builder.boostFactor` must be a valid number without decimals.
 
 Example 1: I will only accept a builder block with 25% more value than the local execution block.
+
 ```
 10000/(100+25) = 80
 ```
+
 Therefore, `--builder.boostFactor=80`.
 
 Example 2: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails.
@@ -107,14 +109,17 @@ Example 3: Setting a `--builder.boostFactor=100` is the same as signaling `--bui
 Please use the official Ethereum Launchpad to perform your deposits. Ensure your deposits are sent to the proper beacon chain deposit address on the correct network.
 
 #### Mainnet
+
 - [Ethereum Mainnet Launchpad](https://launchpad.ethereum.org)
 - [Beacon Chain Deposit Contract](https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa) `0x00000000219ab540356cBB839Cbe05303d7705Fa`
 
 #### Holesky Testnet
+
 - [Ethereum Holesky Testnet Launchpad](https://holesky.launchpad.ethereum.org)
 - [Holesky Beacon Chain Deposit Contract](https://holesky.etherscan.io/address/0x4242424242424242424242424242424242424242) `0x4242424242424242424242424242424242424242`
 
 #### Ephemery Testnet
+
 - [Ethereum Ephemery Testnet Launchpad](https://launchpad.ephemery.dev/)
 - [Ephemeral Testnet Resources](https://ephemery.dev/)
 

diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts
@@ -90,7 +90,7 @@ function renderExamplesSection(examples: CliExample[], sectionTitle?: string, lo
 function renderOption(optionName: string, option: CliOptionDefinition): string | undefined {
   if (option.hidden) return;
 
-  const commandOption = [`<h3 id='-${optionName}'><code>--${optionName}</code><a href="#-${optionName}" class="hash-link" title="--${optionName}"></a></h3>`];
+  const commandOption = [`#### \`--${optionName}\``];
   if (option.description) commandOption.push(`description: ${sanitizeDescription(option.description)}`);
 
   if (option.demandOption === true) {
@@ -254,7 +254,7 @@ export function renderCommandPage(
   globalOptions: CliCommandOptions<Record<never, never>>,
   lodestarCommand?: string
 ): string {
-  const page = [`---\ntitle: CLI Reference\ntoc_min_heading_level: 2\ntoc_max_heading_level: 5\n---\n\n# \`${cmd.command}\` CLI Command`, cmd.describe];
+  const page = [`---\ntitle: CLI Reference\n---\n\n# \`${cmd.command}\` CLI Command`, cmd.describe];
 
   const subCommands = (cmd.subcommands ?? []).map((sub) => getSubCommands(cmd.command, sub)).flat();
   if (subCommands.length > 0) {

diff --git a/packages/light-client/README.md b/packages/light-client/README.md
@@ -63,15 +63,15 @@ const logger = getLcLoggerConsole({logDebug: Boolean(process.env.DEBUG)});
 const api = getClient({urls: ["https://beacon-node.your-domain.com"]}, {config});
 
 const lightclient = await Lightclient.initializeFromCheckpointRoot({
-    config,
-    logger,
-    transport: new LightClientRestTransport(api),
-    genesisData: await getGenesisData(api),
-    checkpointRoot: await getFinalizedSyncCheckpoint(api),
-    opts: {
-        allowForcedUpdates: true,
-        updateHeadersOnForcedUpdate: true,
-    }
+  config,
+  logger,
+  transport: new LightClientRestTransport(api),
+  genesisData: await getGenesisData(api),
+  checkpointRoot: await getFinalizedSyncCheckpoint(api),
+  opts: {
+    allowForcedUpdates: true,
+    updateHeadersOnForcedUpdate: true,
+  },
 });
 
 // Wait for the lightclient to start
@@ -80,11 +80,11 @@ await lightclient.start();
 logger.info("Lightclient synced");
 
 lightclient.emitter.on(LightclientEvent.lightClientFinalityHeader, async (finalityUpdate) => {
-    logger.info(finalityUpdate);
+  logger.info(finalityUpdate);
 });
 
 lightclient.emitter.on(LightclientEvent.lightClientOptimisticHeader, async (optimisticUpdate) => {
-    logger.info(optimisticUpdate);
+  logger.info(optimisticUpdate);
 });
 ```