Skip to content

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

Merged
elizabethengelman merged 6 commits into
mainfrom
feat/add_aliases_to_markdown
Jun 10, 2025
Merged

feat(markdown docs): add aliases to options and subcommands#1771
elizabethengelman merged 6 commits into
mainfrom
feat/add_aliases_to_markdown

Conversation

@willemneal

Copy link
Copy Markdown
Contributor

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 willemneal force-pushed the feat/add_aliases_to_markdown branch 5 times, most recently from 57c5af4 to f62ba24 Compare December 2, 2024 21:12
@willemneal willemneal changed the title feat(markdown docs): add aliases to options feat(markdown docs): add aliases to options and subcommands Dec 3, 2024
@willemneal willemneal force-pushed the feat/add_aliases_to_markdown branch from f62ba24 to 21b4bf1 Compare December 3, 2024 19:10
@willemneal

Copy link
Copy Markdown
Contributor Author

@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 willemneal marked this pull request as ready for review December 3, 2024 19:12
@willemneal willemneal self-assigned this Dec 3, 2024
@github-actions

github-actions Bot commented Jan 4, 2025

Copy link
Copy Markdown
Contributor

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

github-actions Bot commented Mar 1, 2025

Copy link
Copy Markdown
Contributor

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 github-actions Bot added the stale label Mar 1, 2025
@janewang janewang moved this from Needs Review to In Progress in DevX May 7, 2025
@github-actions github-actions Bot removed the stale label May 8, 2025
@elizabethengelman

Copy link
Copy Markdown
Contributor

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 elizabethengelman force-pushed the feat/add_aliases_to_markdown branch from 7cd847c to ea4f40b Compare May 15, 2025 20:26
@leighmcculloch

leighmcculloch commented May 16, 2025

Copy link
Copy Markdown
Member

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

@elizabethengelman elizabethengelman enabled auto-merge (squash) May 21, 2025 14:01
@elizabethengelman elizabethengelman moved this from In Progress to Needs Review in DevX May 21, 2025
@elizabethengelman elizabethengelman merged commit 24a4afa into main Jun 10, 2025
34 checks passed
@elizabethengelman elizabethengelman deleted the feat/add_aliases_to_markdown branch June 10, 2025 20:37
@github-project-automation github-project-automation Bot moved this from Needs Review to Done in DevX Jun 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

5 participants