💥 Update metavar printing

[svlandeg]

WIP: please don't review/comment yet 🙏

Description

We've decided to change a bit the "metavar" printing functionality of Typer. In short, the new rules are:

• consistently use <> for displaying the type (including enum choices etc)
• [] for displaying something optional
• {} for referencing an object (i.e. not a literal string) if neither of the other 2 apply
• AVOID ALL CAPS

Breaking changes

• metavar types now show up as the Python type lowercased (without exception) and in <>, so "<str>" instead of "TEXT" and "<int>" instead of "INTEGER" etc.
• Choices follow the same format so <simple|conv|lstm> instead of [simple|conv|lstm] or {simple|conv|lstm>}. Check the new test test_param_type_help_metavar for an overview.
• metavar names are now cased as the declared name and put between brackets{} in the usage strings, unless they're already surrounded with the "optional" denoting brackets [].
• parameter names are not magically lowercased or uppercased, they are just kept as declared in the Python code. cf. new test test_parameter_name_casing.

Tangiantel fix

• While updating all docs, I realised that we didn't update them when we merged the fix to not display Default: None in the help text, PR 1120. I updated those as part of the documentation update here. I could also do this in a separate PR if preferred, but it would cause a lot of merge conflicts and duplicate work as I've now been going through all the docs in detail anyway.
• Similarly, some docs still needed updating after PR 944 :hide-the-pain-emoji:

Documentation updates

When updating the documentation to show e.g. <str> instead of TEXT, this would be treated as an HTML tag and not actually displayed in our tutorial pages 😭 Hence the fixes to custom.js.

How to review this PR

Please mostly look at the test/documentation changes, and not so much the actual code changes in the Python files. Those will become obsolete with the Pydantic refactor that is in the works. In fact, this PR is a "spinoff" of the Pydantic refactor (#1831, WIP) in an attempt to make that one more "reviewable". The code changes here will be subsumed by that PR.

AI Disclaimer

Created through pair-programming with Cursor, manually reviewed in detail. Also went through all the Typer docs manually & in detail.

Checklist

• I added tests for the change.
• The new or updated tests fail on the main branch and pass on this PR.
• Coverage stays at 100%.
• The documentation/tutorial has been updated to reflect the new help formatting
  • Note to self: continue from https://18f59613.typertiangolo.pages.dev/tutorial/typer-app/

[github-actions]

📝 Docs preview

Last commit df30ebc at: https://18f59613.typertiangolo.pages.dev

Modified Pages

• https://18f59613.typertiangolo.pages.dev/ - (before)
• https://18f59613.typertiangolo.pages.dev/js/custom.js - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/arguments/default/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/arguments/envvar/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/arguments/help/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/arguments/optional/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/commands/arguments/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/commands/callback/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/commands/help/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/commands/one-or-multiple/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/first-steps/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/multiple-values/arguments-with-multiple-values/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/multiple-values/options-with-multiple-values/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/one-file-per-command/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/callback-and-context/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/help/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/name/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/prompt/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/required/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/options/version/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/parameter-types/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/parameter-types/enum/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/typer-app/ - (before)
• https://18f59613.typertiangolo.pages.dev/tutorial/typer-command/ - (before)