fix: Ensure aliases are visible in auto-generated markdown (#1545)

[devcollinss]

What

This change updates the markdown generation process to include aliases for both commands and arguments in the generated documentation.

Why

This change updates the markdown generation process to include aliases for both commands and arguments in the generated documentation.

Known limitations

N\A

[devcollinss]

@willemneal, kindly review the PR. Also, could you please share your preferred means of communication—Discord or Telegram?

[willemneal]

Darn! I wrote a longer response but it didn't get commented!

The summary is that you need to use get_visible_aliases instead. Using short aliases was a mistake we made early on, but for better readability in scripts it's better to use full words as it can be confusing reading it later which arg the short corresponds to. e.g. if two args start with s, what is -s? . So the short aliases can be for power users and they can find it with --help. But for the markdown I suggest we just highlight the normal aliases as these save space but are readable.

Also the aliases should appear inline with their argument.
e.g.

* --source-account, --source

Having them at the bottom will not help devs to discover them and this is more inline with the --help.

Note that rust field names become kebab case when converted to be a CLI arg. So you should be able to take your current setup and insert aliases by finding the corresponding arguments after converting the name kebab-case and adding the alias after like the example above.

Lastly, this bug seems like an issue for upstream clap-markdown itself since this would be the case for any markdown generated by it not just ours. However, given the scope of this work I think this is a fine compromise and won't rely on waiting for upstream releases.

As for communication Discord is preferred, but perhaps best to open an issue on the discord Dev channel so that others can also reply. And feel free to tag me (sir - willem), just the letters, didn't want the full thing in plain text (although an LLM could still figure it out lol).

[devcollinss]

@willemneal i just updated the repo. please review it