soroban-cli icon indicating copy to clipboard operation
soroban-cli copied to clipboard

feat(markdown docs): add aliases to options and subcommands

Open willemneal opened this issue 11 months ago • 3 comments
trafficstars

Move cargo md-gen to an ignored test. This allows moving clap-markdown to dev-dependency allowing the use of a fork and removing an unneeded dependency since the markdown generation is pre-release.

willemneal avatar Dec 02 '24 17:12 willemneal

@leighmcculloch Is it reasonable to make an exception for cargo-deny it is a dev dependency under our control and only impacts generating docs. I'm not sure how long it will take my upstream changes to land.

willemneal avatar Dec 03 '24 19:12 willemneal

This pull request is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed.

github-actions[bot] avatar Jan 04 '25 18:01 github-actions[bot]

This pull request is stale because it has been open for 30 days with no activity. It will be closed in 90 days unless the stale label is removed.

github-actions[bot] avatar Mar 01 '25 18:03 github-actions[bot]

clap-markdown merged in Willem's PR! So, we can now use the upstream dep instead of our fork. One thing to note is that in a follow up PR on clap-markdown, there was a small change to where the aliases are included in the generated markdown:

  • Print command aliases only in their dedicated section, not in the subcommands listing of the parent command.
  • Move the command aliases out of the command header (simplifying the generated anchor link text) and into a bolded section underneath.

For example, using Willem's fork, the docs for would look like this for stellar keys public-key:

## `stellar keys`

Create and manage identities including keys and addresses

**Usage:** `stellar keys <COMMAND>`

###### **Subcommands:**

* `add` — Add a new identity (keypair, ledger, OS specific secure store)
* `public-key` **[alias: `address`]** — Given an identity return its address (public key)
...
## `stellar keys public-key` **[alias: `address`]**

Given an identity return its address (public key)

**Usage:** `stellar keys public-key [OPTIONS] <NAME>`

But with upstream clap-markdown, it removes the [alias: ...] and adds a Command Alias section at the bottom of each command section.

## `stellar keys`

Create and manage identities including keys and addresses

**Usage:** `stellar keys <COMMAND>`

###### **Subcommands:**

* `add` — Add a new identity (keypair, ledger, OS specific secure store)
* `public-key` — Given an identity return its address (public key)
...

## `stellar keys public-key`

Given an identity return its address (public key)

**Usage:** `stellar keys public-key [OPTIONS] <NAME>`

**Command Alias:** `address`

elizabethengelman avatar May 15 '25 19:05 elizabethengelman

👍🏻 I think it's worth using upstream even with the difference, just so we continue to track upstream. Thanks @willemneal for contributing that upstream!

leighmcculloch avatar May 16 '25 03:05 leighmcculloch