Documentation Link

No response

Problem

The :rc: directive always shows defaults. This can be undesired as in

Suggested improvement

We should have two directives, with and without listing the default.

Historic context

:rc: was primarily motivated though parameter specifications such as

where a default value regularly made sense.

Also back then, the link just went to a generic rcsetup page, not to individual parameters. Since we nowadays link to individual parameters, which state the default value. rc without stating the default is more practical as the default value can still be reached relatively easily through the link.

Proprosal

The major decision point is naming. I'm inclined to make :rc: the one without default value and add :rcd: for including the default. This is technically a breaking change of the :rc: directive, but I consider it mostly internal, and even if some external docs use it, the removal of the default should not be too disruptive.

I want to keep the directive as short as possible so that it ideally fits in one line for type information in docstrings:

        capsize : float, default: :rc:`errorbar.capsize`
           The length of the error bar caps in points.

:rc-def: or :rc-default: may already become too long for some parameters.

Also the alternative of keeping :rc: with default and adding :rc-nodefault: feels a bit wrong. To me it's not quite intuitive that :rc: should show the default by default.

Feedback welcome.