[Http client] Confusing 'max_retries' entry

[hellomedia]

In the http_client configuration doc, it seems at first glance that max_retries is a direct child of http_client :

framework.http_client.max_retries

But this config

framework:
    http_client:
        max_retries: 3

gives me this error

Unrecognized option "max_retries" under "framework.http_client".

It seems that max_retries lives under retry_failed instead

$ bin/console debug:config framework

    http_client:
        default_options:
            retry_failed:
                enabled: false
                retry_strategy: null
                http_codes: {  }
                max_retries: 3
                delay: 1000
                multiplier: 2
                max_delay: 0
                jitter: 0.1

This part in the doc hints to the right placement, but isn't it a bit confusing ?

[javiereguiluz]

The framework.http_client. prefix is added automatically using JavaScript when browsing the page. But, that prefix is calculated based on the structure of the config option.

As you said, max_retries is defined in the original doc source as a heading with the same level of the other options. That's why it's considered a direct option of http_client.

If this is confirmed, the solution is to move the options that are children of retry_failed under it and use the level 5 heading marker (") instead of the current level 4 (.):

Before

.. _reference-http-client-retry-max-retries:

max_retries
...........

**type**: ``integer`` **default**: ``3``

The maximum number of retries for failing requests. When the maximum is reached,
[...]

retry_failed
............

**type**: ``array``

This option configures the behavior of the HTTP client when some request fails,
[...]

After

retry_failed
............

**type**: ``array``

This option configures the behavior of the HTTP client when some request fails,
[...]

.. _reference-http-client-retry-max-retries:

max_retries
"""""""""""

**type**: ``integer`` **default**: ``3``

The maximum number of retries for failing requests. When the maximum is reached,
[...]

Anyone up for a quick PR to fix this? 🙏 Thanks!

[hellomedia]

Thanks for the clear guidelines ! I will give it a try

[javiereguiluz]

Closed by #21462. Thanks!