[docs]: update reference section

Signed-off-by: Dmitry Balashov <[email protected]>

.vitepress/config.mts

@@ -65,9 +65,13 @@ function sidebarReference(): DefaultTheme.SidebarItem[] {
     {
       text: 'Reference',
       items: [
+        {
+          text: 'CLI',
+          link: '/reference/cli',
+        },
         {
           text: 'Torii Endpoints',
-          link: '/reference/torii-endpoints.md',
+          link: '/reference/torii-endpoints',
         },
         {
           text: 'Data Model Schema',
@@ -79,12 +83,16 @@ function sidebarReference(): DefaultTheme.SidebarItem[] {
         },
         {
           text: 'Queries',
-          link: '/reference/queries.md',
+          link: '/reference/queries',
         },
         {
           text: 'Permissions',
-          link: '/reference/permissions.md',
+          link: '/reference/permissions',
         },
+        {
+          text: 'Genesis Block',
+          link: '/reference/genesis'
+        }
       ],
     },
     {
@@ -106,6 +114,18 @@ function sidebarReference(): DefaultTheme.SidebarItem[] {
               text: 'Genesis',
               link: '/reference/config/genesis-params',
             },
+            {
+              text: 'Network',
+              link: '/reference/config/network-params',
+            },
+            {
+              text: 'Torii',
+              link: '/reference/config/torii-params',
+            },
+            {
+              text: 'Sumeragi',
+              link: '/reference/config/sumeragi-params',
+            },
             {
               text: 'Kura',
               link: '/reference/config/kura-params',
@@ -122,30 +142,30 @@ function sidebarReference(): DefaultTheme.SidebarItem[] {
               text: 'Snapshot',
               link: '/reference/config/snapshot-params',
             },
-
-            {
-              text: 'Sumeragi',
-              link: '/reference/config/sumeragi-params',
-            },
             {
               text: 'Telemetry',
               link: '/reference/config/telemetry-params',
             },
-
             {
-              text: 'Torii',
-              link: '/reference/config/torii-params',
+              text: 'Chain Wide',
+              link: '/reference/config/chain-wide-params',
             },
           ],
         },
-
         {
           text: 'Glossary',
           link: '/reference/config/glossary',
         },
+      ],
+    },
+    {
+      text: 'Client CLI',
+      items: [
         {
-          text: 'Deprecation and Migration',
-          link: '/reference/config/deprecation-and-migration',
+          text: 'CLI',
+        },
+        {
+          text: 'Configuration',
         },
       ],
     },

.vitepress/theme/components/ConfigParameterSpecs.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { computedEager } from '@vueuse/core'
+import { withBase } from 'vitepress'
+import { match, P } from 'ts-pattern'
+
+const props = defineProps<{
+  type: 'string' | 'number' | 'socket-addr' | 'duration' | 'bytes' | 'private-key' | 'multihash' | 'file-path'
+  defaultValue?: string
+  env?: boolean | string
+}>()
+
+function glossaryLink(text: string, id: string) {
+  return { text, url: withBase(`/reference/config/glossary#${id}`) }
+}
+
+const typeModel = computed(() => {
+  type Result = (string | { url: string; text: string })[]
+
+  return match(props.type)
+    .returnType<Result>()
+    .with('string', () => ['String'])
+    .with('number', () => ['Number'])
+    .with('socket-addr', () => ['String, ', glossaryLink('Socket Address', 'type-socket-address')])
+    .with('duration', () => ['String, ', glossaryLink('Duration', 'type-duration')])
+    .with('bytes', () => ['String, ', glossaryLink('Bytes', 'type-bytes')])
+    .with('private-key', () => ['Table, ', glossaryLink('Private Key', 'type-private-key')])
+    .with('multihash', () => ['String, ', glossaryLink('Multihash', 'type-multihash')])
+      .with('file-path', () => ['String, file path'])
+    .exhaustive()
+})
+</script>
+
+<template>
+  <table>
+    <thead>
+      <tr>
+        <th>Type</th>
+        <th v-if="env">Environment Alias</th>
+        <th v-if="defaultValue">Default</th>
+        <th v-else></th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>
+          <template v-for="item in typeModel">
+            <template v-if="typeof item === 'string'">{{ item }}</template>
+            <a v-else :href="item.url">{{ item.text }}</a>
+          </template>
+        </td>
+        <td v-if="env">
+          <code v-if="typeof env === 'string'">{{ env }}</code>
+          <slot name="env" v-else />
+        </td>
+        <td v-if="defaultValue">
+          {{ defaultValue }}
+        </td>
+        <td v-else>
+          <b>Required</b>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</template>

.vitepress/theme/index.ts

@@ -22,5 +22,9 @@ export default {
       'CompatibilityMatrixTableIcon',
       defineAsyncComponent(async () => import('./components/CompatibilityMatrixTableIcon.vue')),
     )
+    app.component(
+      'ConfigParameterSpecs',
+      defineAsyncComponent(() => import('./components/ConfigParameterSpecs.vue')),
+    )
   },
 }

src/reference/cli.md

@@ -4,16 +4,73 @@ TODO
 
 ## `--config`
 
-Alias: `-c`
+- **Type:** File Path
+- **Required**
+- **Alias:** `-c`
 
-Env: `IROHA_CONFIG`
+Path to the [configuration](/reference/config/) file.
 
-TODO
+```shell
+iroha --config path/to/iroha.toml
+```
 
-## `--trace-config`
+::: tip
 
-TODO
+Paths parameters in the config file are resolved relative to its own
+location. See how
+[paths resolution](/reference/config/glossary#paths-resolution) works.
+
+:::
+
+## `--terminal-colors`
+
+- **Type:** Boolean, either `--terminal-colors=false` or
+  `--terminal-colors=true`
+- **Default:** Auto-detect
+- **ENV:** `TERMINAL_COLORS`
+
+Whether to enable ANSI-colored output or not.
+
+By default, Iroha determines whether the terminal supports colored output
+or not.
+
+To explicitly disable colors:
+
+```shell 
+iroha --terminal-colors=false
+
+# or via env
+
+set TERMINAL_COLORS=false
+iroha
+```
 
 ## `--submit-genesis`
 
-TODO
+- **Type:** Flag, either set or omitted
+
+Whether the current peer should submit the genesis block or not.
+
+Only one peer in the network should submit the genesis block.
+
+This argument must be set alongside with
+[`genesis.file`](/reference/config/genesis-params#genesis-file) and
+[`genesis.private_key`](/reference/config/genesis-params#genesis-private-key)
+configuration parameters. If not, Iroha will exit with an error.
+
+In case when the network consists only of this one peer, i.e. the amount of
+trusted peers in the configuration
+([`sumeragi.trusted_peers`](/reference/config/sumeragi-params#sumeragi-trusted-peers))
+is less than 2, this peer must submit the genesis, since there are no other
+peers who can provide it. In this case, Iroha will exit with an error if
+`--submit-genesis` is not set.
+
+**Examples:**
+
+```shell
+# the peer that doesn't submit the genesis block
+iroha
+
+# the peer submits the genesis
+iroha --submit-genesis
+```

src/reference/config/base-params.md

@@ -1,35 +1,58 @@
 # Base Parameters
 
-## `address`
+## `chain_id`
 
-- **Type:** String, [Socket-Address](glossary#type-socket-address)
-- **Required**
+<ConfigParameterSpecs type="string" env="CHAIN_ID" />
 
-Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes.
+::: code-group
 
-```toml
-address = "localhost:1337"
+```toml [Config File]
+chain_id = "00000000-0000-0000-0000-000000000000"
 ```
 
+```shell [ENV]
+CHAIN_ID=00000000-0000-0000-0000-000000000000
+```
+
+:::
+
 ## `private_key`
 
-- **Type:** Table, [Private Key](glossary#type-private-key)
-- **Required**
+<ConfigParameterSpecs type="private-key" env>
+    <template #env>
+        <code>PRIVATE_KEY_ALGORITHM</code> + <code>PRIVATE_KEY_PAYLOAD</code>
+    </template>
+</ConfigParameterSpecs>
 
-Private key of this peer
+Private key of the peer
+
+::: code-group
+
+```toml [Config File]
+private_key = { algorithm = "ed25519", payload = "8f4c15e5d664da3f13778801d23d4e89b76e94c1b94b389544168b6cb894f84f8ba62848cf767d72e7f7f4b9d2d7ba07fee33760f79abe5597a51520e292a0cb" }
+```
 
-```toml
-private_key.digest = "ed25519"
-private_key.payload = "82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B"
+```shell [ENV]
+PRIVATE_KEY_ALGORITHM=ed25519
+PRIVATE_KEY_PAYLOAD=8f4c15e5d664da3f13778801d23d4e89b76e94c1b94b389544168b6cb894f84f8ba62848cf767d72e7f7f4b9d2d7ba07fee33760f79abe5597a51520e292a0cb
 ```
 
+:::
+
 ## `public_key`
 
-- **Type:** String, [Multi-hash](glossary#type-multi-hash)
-- **Required**
+<ConfigParameterSpecs type="multihash" env="PUBLIC_KEY" />
+
+Public key of the peer
 
-Public key of this peer
+::: code-group
 
-```toml
+```toml [Config File]
 public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9"
 ```
+
+```shell [ENV]
+PUBLIC_KEY=ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9
+```
+
+:::

src/reference/config/chain-wide-params.md

@@ -0,0 +1,5 @@
+# On-Chain Parameters
+
+- These parameters are chain-wide, and each peer should have the same
+- It should not be specified in the config file: https://github.com/hyperledger/iroha/issues/4028
+- We don't document it for now