feat docs: use schemas for documentation in more cases

apolukhin · apolukhin · commit e7c7a42aeac3 · 2025-11-27T23:08:20.000+03:00
Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше)
commit_hash:3e27bfb18588c398d9ec65eccdcf515415fdee09
diff --git a/postgresql/include/userver/storages/postgres/component.hpp b/postgresql/include/userver/storages/postgres/component.hpp
@@ -18,8 +18,6 @@ USERVER_NAMESPACE_BEGIN
 
 namespace components {
 
-// clang-format off
-
 /// @ingroup userver_components
 ///
 /// @brief PosgreSQL client component
@@ -117,33 +115,11 @@ namespace components {
 /// Please see [PostgreSQL documentation](https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNSTRING)
 /// on connection strings.
 ///
-/// ## Static options:
-/// Name                    | Description                                                                   | Default value
-/// ----------------------- | ----------------------------------------------------------------------------- | -------------
-/// dbalias                 | name of the database in secdist config (if available)                         | --
-/// name_alias              | name alias to use in dynamic configs                                          | name of the component
-/// dbconnection            | connection DSN string (used if no dbalias specified)                          | --
-/// blocking_task_processor | name of task processor for background blocking operations                     | engine::current_task::GetBlockingTaskProcessor()
-/// max_replication_lag     | replication lag limit for usable replicas. If a replica's lag exceeds this value, it stops receiving new requests | 60s
-/// sync-start              | perform initial connections synchronously                                     | true
-/// dns_resolver            | server hostname resolver type (getaddrinfo or async)                          | 'async'
-/// persistent-prepared-statements | cache prepared statements or not                                       | true
-/// user-types-enabled      | allow use of user-defined types                                               | true
-/// check-user-types        | cancel service start if some user types have not been loaded, which helps to detect missing migrations | false
-/// ignore_unused_query_params| disable check for not-NULL query params that are not used in query          | false
-/// monitoring-dbalias      | name of the database for monitorings                                          | calculated from dbalias or dbconnection options
-/// max_prepared_cache_size | prepared statements cache size limit                                          | 200
-/// max_statement_metrics   | limit of exported metrics for named statements                                | 0
-/// min_pool_size           | number of connections created initially by this component instance to each of the provided PostgreSQL hosts. Connections are kept even without requests | 4
-/// max_pool_size           | maximum number of connections that can be created by this component instance to each of the provided hosts for "connlimit_mode: manual". Should not be less than `min_pool_size` | 15
-/// max_queue_size          | maximum number of clients waiting for a connection. storages::postgres::PoolError is thrown if a new request exceeds this limit.                        | 200
-/// connecting_limit        | limit for concurrent establishing connections number per PostgreSQL host (0 - unlimited)                                                                | 0
-/// connlimit_mode          | max_connections setup mode (manual or auto), also see @ref scripts/docs/en/userver/pg_connlimit_mode_auto.md                                            | auto
-/// error-injection         | artificial error injection settings, error_injection::Settings                | --
-/// deadline-propagation-enabled | whether deadline propagation sets statement timeout                      | true
-
-// clang-format on
-
+/// ## Static options of @ref components::Postgres :
+/// @include{doc} scripts/docs/en/components_schema/postgresql/src/storages/postgres/component.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 class Postgres : public ComponentBase {
 public:
     /// Default shard number
diff --git a/postgresql/include/userver/storages/postgres/dist_lock_component_base.hpp b/postgresql/include/userver/storages/postgres/dist_lock_component_base.hpp
@@ -14,8 +14,6 @@ USERVER_NAMESPACE_BEGIN
 
 namespace storages::postgres {
 
-// clang-format off
-
 /// @ingroup userver_components userver_base_classes
 ///
 /// @brief Base class for postgres-based distlock worker components
@@ -43,18 +41,11 @@ namespace storages::postgres {
 /// ```
 /// See config `POSTGRES_DISTLOCK_SETTINGS`, some of parameters can be dynamically overridden.
 ///
-/// ## Static options:
-/// name           | Description  | Default value
-/// -------------- | ------------ | -------------
-/// cluster        | postgres cluster name | --
-/// table          | table name to store distlocks | --
-/// lockname       | name of the lock | --
-/// lock-ttl       | TTL of the lock; must be at least as long as the duration between subsequent cancellation checks, otherwise brain split is possible | --
-/// pg-timeout     | timeout, must be less than lock-ttl/2 | --
-/// restart-delay  | how much time to wait after failed task restart | 100ms
-/// autostart      | if true, start automatically after component load | false
-/// task-processor | the name of the TaskProcessor for running DoWork | main-task-processor
-/// testsuite-support | Enable testsuite support | false
+/// ## Static options of @ref storages::postgres::DistLockComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/postgresql/src/storages/postgres/dist_lock_component_base.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ## Migration example
 ///
@@ -71,9 +62,6 @@ namespace storages::postgres {
 /// ```
 ///
 /// @see @ref scripts/docs/en/userver/periodics.md
-
-// clang-format on
-
 class DistLockComponentBase : public components::ComponentBase {
 public:
     DistLockComponentBase(const components::ComponentConfig&, const components::ComponentContext&);
diff --git a/redis/include/userver/storages/redis/component.hpp b/redis/include/userver/storages/redis/component.hpp
@@ -36,8 +36,6 @@ class ThreadPools;
 
 namespace components {
 
-// clang-format off
-
 /// @ingroup userver_components
 ///
 /// @brief Valkey and Redis client component
@@ -55,20 +53,11 @@ namespace components {
 /// * @ref REDIS_SUBSCRIPTIONS_REBALANCE_MIN_INTERVAL_SECONDS
 /// * @ref REDIS_WAIT_CONNECTED
 ///
-/// ## Static options:
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// thread_pools.redis_thread_pool_size | thread count to serve Redis requests | -
-/// thread_pools.sentinel_thread_pool_size | thread count to serve sentinel requests. | -
-/// groups | array of redis clusters to work with excluding subscribers | -
-/// groups.[].config_name | key name in secdist with options for this cluster | -
-/// groups.[].db | name to refer to the cluster in components::Redis::GetClient() | -
-/// groups.[].sharding_strategy | one of RedisCluster, RedisStandalone, KeyShardCrc32, KeyShardTaximeterCrc32 or KeyShardGpsStorageDriver | "KeyShardTaximeterCrc32"
-/// groups.[].allow_reads_from_master | allows read requests from master instance | false
-/// subscribe_groups | array of redis clusters to work with in subscribe mode | -
-/// subscribe_groups.[].config_name | key name in secdist with options for this cluster | -
-/// subscribe_groups.[].db | name to refer to the cluster in components::Redis::GetSubscribeClient() | -
-/// subscribe_groups.[].sharding_strategy | either RedisCluster or KeyShardTaximeterCrc32 | "KeyShardTaximeterCrc32"
+/// ## Static options of @ref components::Redis :
+/// @include{doc} scripts/docs/en/components_schema/redis/src/storages/redis/component.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ## Static configuration example:
 ///
@@ -131,8 +120,6 @@ namespace components {
 /// 1. `"shards"` field is ignored, you can specify an empty array there;
 /// 2. `"sentinels"` field should contain some of the cluster nodes. They are
 ///    only used for topology discovery; it is not necessary to list all nodes.
-
-// clang-format on
 class Redis : public ComponentBase {
 public:
     Redis(const ComponentConfig& config, const ComponentContext& component_context);
diff --git a/scripts/docs/components_schema_to_table.py b/scripts/docs/components_schema_to_table.py
@@ -18,20 +18,52 @@ def normalize_default_value(data) -> str:
         return data
 
 
+def visit_object(yaml, prefix: str = ''):
+    properties = yaml.get('properties', {})
+
+    for key, value in properties.items():
+        if value.get('type') == 'array':
+            if value['items'].get('type') == 'object':
+                yield from visit_object(value['items'], prefix + key + '.[].')
+            elif value.get('description') and value['items'].get('description'):
+                description = value['description'].strip()
+                if not description.endswith('.'):
+                    description += '.'
+                description += ' Each of the array elements: ' + value['items']['description']
+
+                value_cloned = value.copy()
+                value_cloned['description'] = description
+                yield (prefix + key + '.[]', value_cloned)
+            elif value.get('description'):
+                yield (prefix + key + '.[]', value)
+            else:
+                yield (prefix + key + '.[]', value['items'])
+        elif value.get('type') == 'object':
+            yield from visit_object(value, prefix + key + '.')
+        else:
+            yield (prefix + key, value)
+
+    additionals = yaml.get('additionalProperties')
+    if additionals is True:
+        yield (prefix + '*', yaml)
+    elif additionals:
+        yield from visit_object(yaml['additionalProperties'], prefix + '*.')
+
+
 def format_schema(yaml) -> str:
     result = ''
-    properties = yaml.get('properties', {})
-    if not properties:
+    key_values = list(visit_object(yaml))
+    if not key_values:
         result += 'No options'
         return result
 
-    max_key_size = max(len(key) for key in properties.keys())
-    max_value_size = max(len(value['description']) for value in properties.values())
+    max_key_size = max(len(key) for key, _ in key_values)
+    max_value_size = max(len(value['description']) for _, value in key_values)
 
     result += f'{"Name":{max_key_size}} | {"Description":{max_value_size}} | Default value\n'
     result += f'{"":-<{max_key_size}} | {"":-<{max_value_size}} | {"":-<16}\n'
 
-    for key, value in properties.items():
+    for key, value in key_values:
         key = key.replace('\n', ' ')
         description = value['description'].replace('\n', ' ')
         default = normalize_default_value(value.get('defaultDescription', '--'))
diff --git a/ydb/include/userver/ydb/component.hpp b/ydb/include/userver/ydb/component.hpp
@@ -25,38 +25,18 @@ namespace impl {
 class Driver;
 }  // namespace impl
 
-// clang-format off
-
 /// @ingroup userver_components
 ///
 /// @brief YDB client component
 ///
-/// Provides access to ydb::TableClient, ydb::TopicClient, ydb::FederatedTopicClient, ydb::CoordinationClient.
+/// Provides access to @ref ydb::TableClient, @ref ydb::TopicClient, @ref ydb::FederatedTopicClient,
+/// @ref ydb::CoordinationClient.
 ///
-/// ## Static options:
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// `credentials-provider` | name of credentials provider component | -
-/// `operation-settings.retries` | default retries count for an operation | 3
-/// `operation-settings.operation-timeout` | default operation timeout in utils::StringToDuration() format | 1s
-/// `operation-settings.cancel-after` | cancel operation after specified string in utils::StringToDuration() format | 1s
-/// `operation-settings.client-timeout` | default client timeout in utils::StringToDuration() format | 1s
-/// `operation-settings.get-session-timeout` | default session timeout in milliseconds | 5s
-/// `databases.<dbname>.endpoint` | gRPC endpoint URL, e.g. grpc://localhost:1234 | -
-/// `databases.<dbname>.database` | full database path, e.g. /ru/service/production/database | -
-/// `databases.<dbname>.credentials` | credentials config passed to credentials provider component | -
-/// `databases.<dbname>.min_pool_size` | minimum pool size for database with name `<dbname>` | 10
-/// `databases.<dbname>.max_pool_size` | maximum pool size for database with name `<dbname>` | 50
-/// `databases.<dbname>.get_session_retry_limit` | retries count to get session, every attempt with a get-session-timeout | 5
-/// `databases.<dbname>.keep-in-query-cache` | whether to use query cache | true
-/// `databases.<dbname>.prefer_local_dc` | prefer making requests to local DataCenter | false
-/// `databases.<dbname>.aliases` | list of alias names for this database | []
-/// `databases.<dbname>.sync_start` | fail on boot time if YDB is not accessible | true
-/// `databases.<dbname>.by-database-timings-buckets-ms` | histogram bounds for by-database timing metrics | 40 buckets with +20% increment per step
-/// `databases.<dbname>.by-query-timings-buckets-ms` | histogram bounds for by-query timing metrics | 15 buckets with +100% increment per step
-
-// clang-format on
-
+/// ## Static options of @ref ydb::YdbComponent :
+/// @include{doc} scripts/docs/en/components_schema/ydb/src/ydb/component.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 class YdbComponent final : public components::ComponentBase {
 public:
     /// @ingroup userver_component_names
diff --git a/ydb/include/userver/ydb/dist_lock/component_base.hpp b/ydb/include/userver/ydb/dist_lock/component_base.hpp
@@ -18,8 +18,6 @@ class TestsuiteTasks;
 
 namespace ydb {
 
-// clang-format off
-
 /// @ingroup userver_components userver_base_classes
 ///
 /// @brief Base class for YDB-based distlock worker components
@@ -34,24 +32,13 @@ namespace ydb {
 ///
 /// @snippet ydb/functional_tests/basic/static_config.yaml  sample-dist-lock
 ///
-/// ## Static options:
-/// name           | Description  | Default value
-/// -------------- | ------------ | -------------
-/// semaphore-name | name of the semaphore within the coordination node | --
-/// database-settings.dbname | the key of the database within ydb component (NOT the actual database path) | --
-/// database-settings.coordination-node | name of the coordination node within the database | --
-/// initial-setup | if true, then create the coordination node and the semaphore unless they already exist | true
-/// task-processor | the name of the TaskProcessor for running DoWork | main-task-processor
-/// node-settings.session-grace-period | the time after which the lock will be given to another host after a network failure | 10s
-/// session-timeout | for how long we will try to restore session after a network failure before dropping it | 5s
-/// restart-session-delay | backoff before attempting to reconnect session after it returns "permanent failure" | 1s
-/// acquire-interval | backoff before repeating a failed Acquire call | 100ms
-/// restart-delay | backoff before calling DoWork again after it returns or throws | 100ms
-/// cancel-task-time-limit | time, within which a cancelled DoWork is expected to finish | 5s
+/// ## Static options of @ref ydb::DistLockComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/ydb/src/ydb/dist_lock/component_base.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// @see @ref scripts/docs/en/userver/periodics.md
-
-// clang-format on
 class DistLockComponentBase : public components::ComponentBase {
 public:
     DistLockComponentBase(const components::ComponentConfig&, const components::ComponentContext&);
