document rich_config decorator + minor change to config

[dwreeves]

We were not documenting the very excellent @rich_config() decorator. I've added that here! I did not go overboard, however; just a couple examples.

I also reorganized the environment variable defaults a bit: notably, int() call is made "safe" and the callables to set these defaults are treated as source of truth for how they are set, rather than repeating the logic across a few places.

---

cc @ewels:

Relatedly, I'm a little worried about these env vars... I am wondering if these names should be deprecated and moved to something with RICH_CLICK_* prefixes in a future release. Another issue is the env vars being eagerly loaded into the global state (this is what motivated me to try-except the int() call, actually). For most users this will not matter as most users are not mutating environment variables between importing rich click and running their CLI. Still, it doesn't feel ideal.

I will likely open an issue about all of this later for more discussion. TLDR: I think in 1.8 we should introduce deprecation warnings that in 2.x all env var support will move to the RICH_CLICK_* namespace (I also wonder if, at that point, you could even make it so every 'simple' config option can be set via an environment variable 👀). And then when we do that, we should document exactly the resolution of config options: The order should be explicitly stated, e.g.: (1) rich_config (2) environment (3) default. Not sure what the order should be, or even if the user should have control over it (maybe even have a config option called ignore_environment!). But this is where my head is regarding the config stuff for future releases.

But, all that said, I am far more worried about just documenting every config option first in a comprehensive way. We will want a list of every config option, what it does, and every way to set it (similar to how for example isort documents their options: https://pycqa.github.io/isort/docs/configuration/options.html).

[ewels]

I would like to be careful before removing any of these env vars. I think that several were named after existing env vars from other packages. For example - my own (rich-codex) but also Rich itself, and GitHub actions maybe?? and other sources.

We could read from prefixed versions as well, which would be safer for anyone wanting to not mess with other tools. But removing the non-prefixed-versions might make the tool stop doing The Right Thing in a bunch of places.

[dwreeves]

Understood! I should have clarified I was not talking about the GH actions one, but good to know that you are relying on them in other places too. I will retract any ideas of removing any! 😅

[dwreeves]

Also, I am opening up a broader discussion about configs here: #134.