feat docs: use schemas for documentation in more cases

Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше)
commit_hash:750bfd01b681b8eba63d3ed36eba35ff96885281

Author: apolukhin

mysql/include/userver/storages/mysql/component.hpp

@@ -20,7 +20,6 @@ class Cluster;
 
 namespace storages::mysql {
 
-// clang-format off
 /// @ingroup userver_components
 ///
 /// @brief MySQL/MariaDB client component
@@ -44,13 +43,11 @@ namespace storages::mysql {
 /// primary detection and always considers the first host in `hosts` list
 /// an only primary node in the cluster.
 ///
-/// ## Static options (more to come)
-/// Name                     | Description                                 | Default value
-/// -------------------------|---------------------------------------------|---------------
-/// initial_pool_size        | initial connection pool size (per host)     | 5
-/// max_pool_size            | maximum connection pool size (per host)     | 10
+/// ## Static options of @ref storages::mysql::Component :
+/// @include{doc} scripts/docs/en/components_schema/mysql/src/storages/mysql/component.md
 ///
-// clang-format on
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 class Component final : public components::ComponentBase {
 public:
     /// Component constructor

rabbitmq/include/userver/urabbitmq/component.hpp

@@ -20,7 +20,6 @@ class Client;
 
 namespace components {
 
-// clang-format off
 /// @ingroup userver_components
 ///
 /// @brief RabbitMQ (AMQP 0.9.1) client component
@@ -42,17 +41,11 @@ namespace components {
 ///
 /// @snippet samples/rabbitmq_service/tests/conftest.py  RabbitMQ service sample - secdist
 ///
-/// ## Static options:
-/// Name                    | Description                                                          | Default value
-/// ----------------------- | -------------------------------------------------------------------- | ---------------
-/// secdist_alias           | name of the key in secdist config                                    | components name
-/// min_pool_size           | minimum connections pool size (per host)                             | 5
-/// max_pool_size           | maximum connections pool size (per host, consumers excluded)         | 10
-/// max_in_flight_requests  | per-connection limit for requests awaiting response from the broker  | 5
-/// use_secure_connection   | whether to use TLS for connections                                   | true
+/// ## Static options of @ref components::RabbitMQ :
+/// @include{doc} scripts/docs/en/components_schema/rabbitmq/src/urabbitmq/component.md
 ///
-// clang-format on
-
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 class RabbitMQ final : public ComponentBase {
 public:
     /// Component constructor

rabbitmq/include/userver/urabbitmq/consumer_component_base.hpp

@@ -11,7 +11,6 @@ USERVER_NAMESPACE_BEGIN
 
 namespace urabbitmq {
 
-// clang-format off
 /// @ingroup userver_base_classes
 ///
 /// @brief Base component for your consumers.
@@ -33,13 +32,11 @@ namespace urabbitmq {
 ///
 /// @snippet samples/rabbitmq_service/static_config.yaml  RabbitMQ consumer sample - static config
 ///
-/// ## Static options:
-/// Name             | Description
-/// rabbit_name      | Name of the RabbitMQ component to use for consumption
-/// queue            | Name of the queue to consume from
-/// prefetch_count   | prefetch_count for the consumer, limits the amount of in-flight messages
+/// ## Static options @ref urabbitmq::ConsumerComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/rabbitmq/src/urabbitmq/consumer_component_base.md
 ///
-// clang-format on
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 class ConsumerComponentBase : public components::ComponentBase {
 public:
     ConsumerComponentBase(const components::ComponentConfig& config, const components::ComponentContext& context);

rabbitmq/src/urabbitmq/consumer_component_base.yaml

@@ -10,4 +10,5 @@ properties:
         description: a queue to consume from
     prefetch_count:
         type: integer
-        description: prefetch_count for the consumer
+        description: prefetch_count for the consumer, limits the amount of in-flight
+            messages

rocks/include/userver/storages/rocks/component.hpp

@@ -13,19 +13,15 @@ USERVER_NAMESPACE_BEGIN
 
 namespace storages::rocks {
 
-// clang-format off
-
 /// @ingroup userver_components
 ///
 /// @brief RocksDB client component.
-/// ## Static options:
-/// Name                               | Description                                      | Default value
-/// ---------------------------------- | ------------------------------------------------ | ---------------
-/// task-processor                     | name of the task processor to run the blocking file operations | -
-/// db-path                            | path to database file                            | -
-
-// clang-format on
-
+///
+/// ## Static options of @ref storages::rocks::Component :
+/// @include{doc} scripts/docs/en/components_schema/rocks/src/storages/rocks/component.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md                         | -
 class Component : public components::ComponentBase {
 public:
     Component(const components::ComponentConfig&, const components::ComponentContext&);

scripts/docs/components_schema_to_table.py

@@ -18,26 +18,32 @@ def normalize_default_value(data) -> str:
         return data
 
 
+def merge_descriptions(yaml, other):
+    if yaml.get('description') and other.get('description'):
+        description = yaml['description'].strip()
+        if not description.endswith('.'):
+            description += '.'
+        description += ' <i>Each of the elements:</i> ' + other['description']
+
+        value_merged = yaml.copy()
+        value_merged['description'] = description
+        return value_merged
+    elif yaml.get('description'):
+        return yaml
+    else:
+        return other
+
+
 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'])
+                value_merged = merge_descriptions(value, value['items'])
+                yield (prefix + key + '.[]', value_merged)
         elif value.get('type') == 'object':
             yield from visit_object(value, prefix + key + '.')
         else:
@@ -46,8 +52,16 @@ def visit_object(yaml, prefix: str = ''):
     additionals = yaml.get('additionalProperties')
     if additionals is True:
         yield (prefix + '*', yaml)
-    elif additionals:
+    elif not additionals:
+        return
+    elif additionals.get('type') == 'object':
         yield from visit_object(yaml['additionalProperties'], prefix + '*.')
+    elif additionals.get('type') == 'array':
+        value_merged = merge_descriptions(yaml, additionals['items'])
+        yield (prefix + '*.[]', value_merged)
+    else:
+        value_merged = merge_descriptions(yaml, additionals)
+        yield (prefix + '*', value_merged)
 
 
 def format_schema(yaml) -> str: