💥 Update metavar printing

[svlandeg]

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 in the usage string
• {} for referencing an object (i.e. not a literal string) in the usage string if neither of the other 2 apply
• AVOID ALL CAPS

Breaking changes

• metavar types now show up as the actual Python type 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.
• 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.
• In the help usage strings, parameter/metavar names are now put between brackets{}, unless they're already surrounded with the "optional" denoting brackets [].
• In the list of "Arguments:", no brackets are printed around the names (on master, optional ones were enclosed with [] which felt inconsistent with optional options)

Edits in custom.js

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.

Tangiantel fixes

• 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:
• I found some other issues with the docs while going through everything in detail, and decided to fix those in this PR as well. Things like defaults not displayed in the example output, or the Arguments list missing, etc. I'm guessing these were mostly manual copy/paste errors from the past 🤷‍♀️

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.

The Python edits 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". Only the docs & tests changes will be brought over from here - the code changes from this PR will be subsumed by PR 1831.

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

[github-actions]

📝 Docs preview

Last commit 00e76e0 at: https://57e738c4.typertiangolo.pages.dev

Modified Pages

• https://57e738c4.typertiangolo.pages.dev/ - (before)
• https://57e738c4.typertiangolo.pages.dev/js/custom.js - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/arguments/default/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/arguments/envvar/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/arguments/help/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/arguments/optional/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/commands/arguments/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/commands/callback/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/commands/help/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/commands/one-or-multiple/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/first-steps/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/multiple-values/arguments-with-multiple-values/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/multiple-values/options-with-multiple-values/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/one-file-per-command/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/callback-and-context/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/help/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/name/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/prompt/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/required/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/options/version/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/bool/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/datetime/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/enum/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/number/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/path/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/parameter-types/uuid/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/subcommands/add-typer/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/subcommands/nested-subcommands/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/typer-app/ - (before)
• https://57e738c4.typertiangolo.pages.dev/tutorial/typer-command/ - (before)

[tiangolo]

Everything looks good! 🙌

This must have been painful to make, going through all the docs. 😅

Thank you!

[svlandeg]

This must have been painful to make, going through all the docs. 😅

Quite 😅

Had to do several sections multiple times, too, after making fixes and going back to make sure everything was consistent 🙈