[docs]: add configuration reference

.vitepress/config.mts

@@ -16,9 +16,9 @@ function getNav(): DefaultTheme.NavItem[] {
       activeMatch: '^/$|^/guide/',
     },
     {
-      text: 'Schema',
-      link: '/data-model-schema/',
-      activeMatch: '^/data-model-schema/',
+      text: 'API',
+      link: '/api/',
+      activeMatch: '^/api/',
     },
   ]
 }
@@ -222,6 +222,10 @@ function getGuideSidebar(): DefaultTheme.SidebarItem[] {
               text: 'Metadata and Store assets',
               link: '/guide/configure/metadata-and-store-assets',
             },
+            {
+              text: '[wip] Reference',
+              link: '/configuration-reference',
+            },
           ],
         },
         {
@@ -280,19 +284,19 @@ function getGuideSidebar(): DefaultTheme.SidebarItem[] {
         },
       ],
     },
-    {
-      text: 'API',
-      items: [
-        {
-          text: 'Specification',
-          link: '/api/index.md',
-        },
-        {
-          text: 'Foreign Function Interfaces',
-          link: '/api/ffi',
-        },
-      ],
-    },
+    // {
+    //   text: 'API',
+    //   items: [
+    //     {
+    //       text: 'Specification',
+    //       link: '/api/index.md',
+    //     },
+    //     {
+    //       text: 'Foreign Function Interfaces',
+    //       link: '/api/ffi',
+    //     },
+    //   ],
+    // },
     {
       text: 'Documenting Iroha',
       items: [
@@ -367,6 +371,7 @@ export default defineConfig({
   themeConfig: {
     // logo: '/icon.svg',
     siteTitle: 'Iroha 2',
+    outline: 'deep',
 
     socialLinks: [
       { icon: 'github', link: 'https://github.com/hyperledger/iroha-2-docs' },
@@ -392,11 +397,104 @@ export default defineConfig({
 
     sidebar: {
       '/guide/': getGuideSidebar(),
-      '/data-model-schema': [
+      '/api/': [
+        {
+          text: 'Overview',
+          link: '/api/',
+        },
+        {
+          text: 'Configuration',
+          link: '/api/configuration',
+        },
+        {
+          text: 'Command Line Interface (CLI)',
+          link: '/api/cli',
+        },
+        {
+          text: 'API Specification',
+          link: '/api/api',
+        },
+        {
+          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: 'Network',
+                  link: '/api/config/network-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: 'Block Sync',
+                  link: '/api/config/block-sync-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: 'Channel',
+          text: 'Data Model Schema',
+          link: '/api/data-model-schema/',
           items: ['stable', 'lts', 'dev'].map((channel) => ({
-            link: `/data-model-schema/${channel}`,
+            link: `/api/data-model-schema/${channel}`,
             text: `iroha2-${channel}`,
           })),
         },

src/api/api.md

@@ -0,0 +1,20 @@
+<script setup>
+import { useData } from 'vitepress'
+
+const { page } = useData()
+</script>
+
+# API Specification
+
+::: info
+
+This page contains a copy of the `api_spec.md` document from
+`hyperledger/iroha#iroha2-dev`. You can read the most up-to-date version
+on
+[GitHub](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/api_spec.md).
+
+Please note this page was last updated on <b>{{ new Date(page.lastUpdated).toLocaleString() }}</b>.
+
+:::
+
+<!--@include: ../snippets/iroha2_dev_api_spec.md -->

src/api/cli.md

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

src/api/config/base-params.md

@@ -0,0 +1,23 @@
+# 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" }
+```

src/api/config/block-sync-params.md

@@ -0,0 +1,27 @@
+# Block Sync Parameters
+
+TODO Explain module
+
+## `block_sync.block_batch_amount`
+
+- **Type:** Number
+- **Default:** $4$
+
+The number of blocks that can be sent in one message.
+
+```toml
+[block_sync]
+block_batch_amount = 4
+```
+
+## `block_sync.gossip_period`
+
+- **Type:** String or Number, [Duration](glossary#type-duration)
+- **Default:** 10 seconds
+
+The period of time to wait between sending requests for the latest block.
+
+```toml
+[block_sync]
+gossip_period = "5 secs"
+```

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.
+
+:::