[suggestion] Enhance configuration reference format

[0x009922]

Feature request

This might be split into 2 separate tasks:

1. Emit configuration reference as a machine-readable file, e.g. JSON
2. Format that structured machine-readable reference as a structured Markdown

The infrastructure for both is almost done. This complain is only about the format.

Related issue:

• Improve doc generation #1639

1. Machine-readable

Sample format:

{
  schema: [
    // leaf root-level field
    // this field doesn't have `value.default`, i.e. it is REQUIRED
    {
      kind: "leaf",
      name: "public_key",
      documentation: "Public key of this peer",
      env: "IROHA_PUBLIC_KEY",
      value: {
        typedoc: "`PublicKey`",
        related_types: ["PublicKey"],
      },
    },
    // group of nested fields
    {
      kind: "nested",
      name: "logger",
      documentation: "Logger configuration",
      items: [
        // this field has `value.default`, i.e. it is OPTIONAL
        {
          kind: "leaf",
          name: "max_log_level",
          documentation: "Maximum log level",
          env: "MAX_LOG_LEVEL",
          value: {
            typedoc: `"TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL"`,
            // this
            default: `"INFO"`,
          },
        },
      ],
    },
    // Contains references to a complex structures
    {
      kind: "nested",
      name: "sumeragi",
      documentation: "Sumeragi configuration",
      items: [
        {
          kind: "leaf",
          name: "trusted_peers",
          documentation: "Optional list of predefined trusted peers.",
          env: "SUMERAGI_TRUSTED_PEERS",
          value: {
            typedoc: "`PeerId`[]",
            default: `\`[]\``,
            example: `[{"address":"iroha0:1337", "public_key": "ed01201C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B"}]`,
            related_types: ["PeerId"],
          },
        },
      ],
    },
  ],
  types: {
    PeerId: {
      kind: "struct",
      documentation: "Peer id?",
      fields: [
        {
          name: "address",
          documentation: "Peer address",
          value: {
            typedoc: "string",
            example: `"iroha0:1337"`,
          },
        },
        {
          name: "public_key",
          documentation: "Peer public key",
          value: {
            typedoc: "`PublicKey`",
            related_types: ["PublicKey"],
          },
        },
      ],
    },
    PublicKey: {
      kind: "simple",
      documentation: "Public key multihash",
      typedoc: "string",
      example: `"ed01201C61FAF8FE94E253B93114240394F79A607B7FA55F9E5A41EBEC74B88055768B"`,
    },
  },
}

TypeScript

interface ConfigReference {
  schema: Array<SchemaItem>;
  types: Record<string, TypeStruct | TypeSimple>;
}

type SchemaItem = SchemaItemLeaf | SchemaItemNested;

interface SchemaItemBase {
  name: string;
  documentation: string;
}

interface SchemaItemLeaf extends SchemaItemBase {
  kind: "leaf";
  value: FieldValue;
  env?: string;
}

interface SchemaItemNested extends SchemaItemBase {
  kind: "nested";
  items: Array<SchemaItem>;
}

interface TypeStruct {
  kind: "struct";
  documentation: string;
  fields: Array<StructureField>;
}

interface TypeSimple {
  kind: "simple";
  documentation: string;
  typedoc: string;
  example?: string;
}

interface StructureField {
  name: string;
  documentation: string;
  value: FieldValue;
}

interface FieldValue {
  typedoc: string;
  default?: string;
  example?: string;
  related_types?: string[];
}

2. Human-readable

Instead of this:

genesis.account_private_key

The private key of the genesis account, only needed for the peer that submits the genesis block.

Has type Option<Option<PrivateKey>>. Can be configured via environment variable IROHA_GENESIS_ACCOUNT_PRIVATE_KEY

null

Would be nicer:

genesis.account_private_key

• Docs: The private key of the genesis account, only needed for the peer that submits the genesis block.
• ENV: IROHA_GENESIS_ACCOUNT_PRIVATE_KEY
• Type: null or PrivateKey
  See:
  • PrivateKey (inner-document link)
• Required: No
• Default value:

  null

Benefits

• Easier to respond to GET /configuration in both machine-readable and human-readable formats
• Easier to throw explanatory errors on misconfiguration
• Ability to emit such a structured format implies a higher-quality code behing configuration in general
• Well-structured machine-readalbe format helps to build consistent and well-structured human-readalbe format.

[0x009922]

Auto-generated config reference was removed in #4127