Make defaulting to rcParams more transparent

[aloctavodia]

Current problems

• Currently, in arviz-stats and arviz-plots, we have arguments that default to None, and then we set them to some value from rcParams. This is always explained in the docstring, but we could have a more self-explanatory value, maybe a string like "rcparams" or "from_rcparams". We could also use more general values like "auto", "default", or something else.

• In many places, we use Defaults to rcParams["data.sample_dims"] instead of Defaults to rcParam :data:data.sample_dims. The second has the advantage that it becomes clickable when rendered to HTML. Currently, we use this inconsistently.

• One issue when reading the docs directly, including reading them with an IDE, is that the actual default value is not known unless we inspect rcParams. Can we automatically populate the docstrings? What else could we do to make it easier for users?

[tomicapretto]

1. I agree the None option is not ideal, as in many cases, when reading the docstring, I still end up wondering what is the exact value used by default. I'm not sure how to improve this, though. I think "auto" is a bit more self explanatory than None, but it still doesn't tell you what the value is. Manually adding the default value of the relevant rcParam would solve this problem, incurring in a large maintenance cost I think. So I'm not sure it's good either.
2. If I understand correctly, you're advocating to use the second option more consistently. I agree it's better.
3. This is connected to point 1 I think. It would be ideal if it could be populated automatically. I think one would need to see if Sphinx has something to provide on this front.

[tomicapretto]

One option to automatically populate rcParam values is the following:

fun.py

from params import rcParams

def f(x, y, z=None):
    """The function

    Parameters
    ----------
    x : int
        A number
    y : int
        Another number
    z : str, optional
        How to do something. If None, defaults to ``rcParams['default_z'] = '{default_z}'``.
    """
    print(z)
    return x + y


# Inject value into docstring
f.__doc__ = f.__doc__.format(default_z=rcParams["default_z"])

params.py

rcParams = {
    "default_z": "THE_VALUE",
}

main.py

from fun import f

f(1, 5)

It does work well when you do help(f) and I think it should work well when rendering with sphinx, but it doesn't work well in my IDE.

[OriolAbril]

It will only work on rendered docs, but we can also copy the matplotlib sphinx extension/customization for rcparams (the rcparams class is basically taken from there too). In the docstring they use a custom defined role :rc: as seen for example in the scatter docstring:

https://github.com/matplotlib/matplotlib/blob/1392cbe3c79cdb93f9282747841d648770f60249/lib/matplotlib/axes/_axes.py#L4840

and the rendered version looks like this:

---

Adding to the discussion about documenting this in general, I see the value in adding the "factory default" somewhere like the docs, but I would not try too hard to get a "live" docstring. For help(object) or the IDE tooltip or similar elements to work we'd have to check when these injections happen. If it is at import time, then loading a theme/template afterwards will make the docstring be kind of wrong (we have substituted the old rcparam but it is still being substituted for something specific). Trying to update docstrings whenever rcparams are modified is probably even more work and for little to gain. Having the substitution on the website docs feels less worrying as I think it makes it a bit more clear those are the "factory defaults"

[tomicapretto]

Having the substitution on the website docs feels less worrying as I think it makes it a bit more clear those are the "factory defaults"

I agree. So... Matplotlib way is the way?

[aloctavodia]

Python 3.15 introduces sentinel values https://docs.python.org/3.15/library/functions.html#sentinel