[docs]: add configuration reference

.vitepress/config.mts

@@ -1,6 +1,6 @@
 /// <reference types="vite/client" />
 
-import { defineConfig, DefaultTheme } from 'vitepress'
+import { DefaultTheme, defineConfig } from 'vitepress'
 import footnote from 'markdown-it-footnote'
 import { resolve } from 'path'
 import ViteSvgLoader from 'vite-svg-loader'
@@ -265,23 +265,6 @@ function getGuideSidebar(): DefaultTheme.SidebarItem[] {
         },
       ],
     },
-    {
-      text: 'API',
-      items: [
-        {
-          text: 'Torii Endpoints',
-          link: '/api/torii-endpoints.md',
-        },
-        {
-          text: 'Foreign Function Interfaces',
-          link: '/api/ffi',
-        },
-        {
-          text: 'Data Model Schema',
-          link: '/api/data-model-schema',
-        },
-      ],
-    },
     {
       text: 'Documenting Iroha',
       items: [
@@ -381,9 +364,112 @@ export default defineConfig({
 
     sidebar: {
       '/guide/': getGuideSidebar(),
+      '/api/': [
+        {
+          text: 'Overview',
+          link: '/api/',
+        },
+        {
+          text: 'Configuration',
+          link: '/api/configuration',
+        },
+        {
+          text: 'Command Line Interface (CLI)',
+          link: '/api/cli',
+        },
+        {
+          text: 'Torii Endpoints',
+          link: '/api/torii-endpoints',
+        },
+        {
+          text: 'Foreign Function Interfaces (FFI)',
+          link: '/api/ffi',
+        },
+        {
+          text: 'Configuration',
+          items: [
+            {
+              text: 'Overview',
+              link: '/api/config/',
+            },
+            {
+              text: 'Parameters',
+              items: [
+                // TODO: consider re-ordering sections to a more intuitive format?
+                {
+                  text: 'Base',
+                  link: '/api/config/base-params',
+                },
+                {
+                  text: 'Genesis',
+                  link: '/api/config/genesis-params',
+                },
+                {
+                  text: 'Sumeragi',
+                  link: '/api/config/sumeragi-params',
+                },
+                {
+                  text: 'Torii',
+                  link: '/api/config/torii-params',
+                },
+                {
+                  text: 'Queue',
+                  link: '/api/config/queue-params',
+                },
+                {
+                  text: 'Kura',
+                  link: '/api/config/kura-params',
+                },
+                {
+                  text: 'Logger',
+                  link: '/api/config/logger-params',
+                },
+                {
+                  text: 'WSV',
+                  link: '/api/config/wsv-params',
+                },
+                {
+                  text: 'Telemetry',
+                  link: '/api/config/telemetry-params',
+                },
+                {
+                  text: 'Snapshot',
+                  link: '/api/config/snapshot-params',
+                },
+              ],
+            },
+
+            {
+              text: 'Glossary',
+              link: '/api/config/glossary',
+            },
+            {
+              text: 'Deprecation and Migration',
+              link: '/api/config/deprecation-and-migration',
+            },
+          ],
+        },
+        {
+          text: 'Data Model Schema',
+          link: '/api/data-model-schema',
+        },
+      ],
       '/': getGuideSidebar(),
     },
 
+    nav: [
+      {
+        text: 'Guide',
+        link: '/',
+        activeMatch: '^/$|^/guide/',
+      },
+      {
+        text: 'API',
+        link: '/api/',
+        activeMatch: '^/api/',
+      },
+    ],
+
     search: {
       provider: 'local',
     },

src/api/cli.md

@@ -0,0 +1,19 @@
+# Command Line Interface (CLI)
+
+TODO
+
+## `--config`
+
+Alias: `-c`
+
+Env: `IROHA_CONFIG`
+
+TODO
+
+## `--trace-config`
+
+TODO
+
+## `--submit-genesis`
+
+TODO

src/api/config/base-params.md

@@ -0,0 +1,35 @@
+# Base Parameters
+
+## `public_key`
+
+- **Type:** String, [Multi-hash](glossary#type-multi-hash)
+- **Required**
+
+Public key of this peer
+
+```toml
+public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9"
+```
+
+## `private_key`
+
+- **Type:** Table, [Private Key](glossary#type-private-key)
+- **Required**
+
+Private key of this peer
+
+```toml
+private_key = { digest = "ed25519", payload = "82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }
+```
+
+
+## `address`
+
+- **Type:** String, [Socket-Address](glossary#type-socket-address)
+- **Required**
+
+Address for p2p communication for consensus (sumeragi) and block synchronization (block_sync) purposes.
+
+```toml
+address = "localhost:1337"
+```

src/api/config/deprecation-and-migration.md

@@ -0,0 +1,3 @@
+# Deprecation and Migration Policy
+
+TODO

src/api/config/genesis-params.md

@@ -0,0 +1,45 @@
+# Genesis Parameters
+
+TODO Explain the purpose of this block. Maybe explain both keys in a single section?
+
+## `genesis.public_key`
+
+- **Type:** [Multi-hash](glossary#type-multi-hash)
+- **Required**
+
+The public key of the genesis account, should be supplied to all peers.
+
+```toml
+[genesis]
+public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9"
+```
+
+## `genesis.private_key`
+
+- **Type:** Table, [Private Key](glossary#type-private-key)
+- **Required** if the configured peer submits the genesis block,
+  **optional** otherwise
+
+The private key of the genesis account, only needed for the peer that
+submits the genesis block.
+
+```toml
+[genesis]
+private_key = { digest = "ed25519", payload = "82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }
+```
+
+::: info
+
+This parameter is required if the peer being configured submits the
+genesis, i.e. if it is run with the [`--submit-genesis`](../cli#submit-genesis)
+CLI argument.
+
+:::
+
+::: warning
+
+The warning will be printed if the
+[`genesis.private_key`](#genesis-private-key) and
+[`--submit-genesis`](../cli#submit-genesis) are used without each other.
+
+:::

src/api/config/glossary.md

@@ -0,0 +1,133 @@
+# Glossary
+
+This page contains the definitions and brief explanations of data types and topics shared across
+multiple configuration parameters.
+
+## Numeric Types
+
+TODO Explain the limitations of different numeric types, like `u8` and `u64`.
+
+## Type: Duration
+
+Duration might be specified in two ways:
+
+- As a Number, which will be considered an amount in milliseconds
+- As a String, which will be parsed as a human-readable string
+
+Numeric setting is straightforward:
+
+```toml
+value = 1000 # 1000 milliseconds
+```
+
+String setting might be more readable:
+
+```toml
+value1 = "1sec"
+value2 = "1hour 12min 5s"
+value3 = "2years 2min 12us"
+```
+
+The duration string is a concatenation of time spans. Each time span is an
+integer number and a suffix. Supported suffixes:
+
+- `nsec`, `ns` — nanoseconds
+- `usec`, `us` — microseconds
+- `msec`, `ms` — milliseconds
+- `seconds`, `second`, `sec`, `s`
+- `minutes`, `minute`, `min`, `m`
+- `hours`, `hour`, `hr`, `h`
+- `days`, `day`, `d`
+- `weeks`, `week`, `w`
+- `months`, `month`, `M` — defined as $30.44$ days
+- `years`, `year`, `y` — defined as $365.25$ days
+
+TODO: put link to
+[`humantime` crate](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)?
+It is an implementation detail.
+
+## Type: Multi-hash
+
+TODO Describe what the hell this is
+
+## Type: Byte Size
+
+Byte size values might be set in two ways:
+
+- As a Number, which will be considered an amount in bytes
+- As a String, which will be parsed as a human-readable string
+
+Byte size as a number:
+
+```toml
+value = 512 # 512 bytes
+```
+
+Byte size as a string:
+
+```toml
+# 42 bytes
+value1 = "42"
+value2 = "42b"
+value3 = "42bytes"
+
+# 1 kilobyte = 1000 bytes
+value4 = "1KB"
+
+# 1 kilobyte (binary format) = 1024 bytes
+value5 = "1KiB"
+
+# Combination of multiple
+value412 = "1GB 5MB"
+```
+
+Iroha can parse sizes in bytes, kilobytes, megabytes, gigabytes, terabytes,
+and petabytes.
+
+The format of suffixes:
+
+- **`{size}iB`:** Binary size
+- **`{size}B`:** Decimal size
+
+TODO: haven't found a rust lib for that. There is a Python one
+([`humanfriendly`](https://humanfriendly.readthedocs.io/en/latest/api.html?highlight=parse_size#humanfriendly.parse_size))
+I used for reference.
+
+TODO: [article explains kb, kB, KiB difference](https://web.archive.org/web/20150324153922/https://pacoup.com/2009/05/26/kb-kb-kib-whats-up-with-that/).
+Consider it for the format.
+
+## Type: Private Key
+
+TODO explain private key
+
+```toml
+private_key = { digest = "ed25519", payload = "" }
+```
+
+## Type: Socket Address
+
+TODO explain socket addresses
+
+```
+<host>:<port>
+```
+
+```
+localhost:8080
+127.0.0.1:1337
+sample.com:9090
+```
+
+In TOML it should be specified as a string:
+
+```toml
+address = "localhost:8000"
+```
+
+## Type: Metadata Limits
+
+TODO
+
+### Default Metadata Limits
+
+TODO Display the value here