Add @custom_version_option, freeze @version_option

[kdeldycke]

This is an attempt to address the design discussion we started in #3527 about @version_option extensibility.

What's in this PR:

• A .. note:: admonition to point to @version_option freeze.
• A new @custom_version_option that mirrors @help_option and @version_option and takes a callback for a custom message.

I did not take the class-based approach here, as it reminded me of the HelpOption class that I was too fast to add in #2563 (v8.1.8) then had to remove in #2832/#2840 (v8.2.0).

If I like the explicitness of the freeze admonition, I don't like the rest of the code: the naming of @custom_version_option and the apparent duplication with @version_option. But I produced this PR anyway to explore the effect of our policy and to have a concrete example to discuss.

[Rowlando13]

@kdeldycke This looks good. Allows for simple customization. I would change the echo to a normal print. I think for most things we can move away from echo.

[Rowlando13]

Let me know what you think about print instead of echo is this case.

[kdeldycke]

Let me know what you think about print instead of echo is this case.

The reason we use echo instead of print is because echo is sensitive to the color state. See how it calls should_strip_ansi. And removing Colorama did not provide any simplification: we still need to adapt printing to the environment (non-tty, Ansi, CLI test runner etc).

So unless you want to reintroduce ANSI-related issues, it's better to do the reverse: always use echo unless we have a good reason to use print. :)

[kdeldycke]

Let me know what you think about print instead of echo is this case.

I used the opportunity to grep into the code and docs and yes, we are properly using echo everywhere. I just fixed one occurence in docs/utils.md and documented the exceptional use of print to demonstrate the page usage. @Rowlando13 if you agree with these changes feel free to merge, just double-check these additions.

[davidism]

Yeah, echo does stuff besides the weird stream stuff (which we do want to remove if possible): https://click.palletsprojects.com/en/stable/api/#click.echo. Only some of those points are (will be) still relevant. We should use it consistently.

[Rowlando13]

Sounds good. So it seems like we should consistently use it internally, but perhaps direct users to use print and echo is they need to. I will start a discussion for it.