feat: Generate CLI documentation automatically #3157
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
olivier-lacroix
force-pushed
the
feat/autodoc
branch
from
653fda9 to
8ed3935
Compare
olivier-lacroix
commented
Feb 18, 2025
| #[derive(Parser, Debug)] | ||
| #[clap(verbatim_doc_comment)] |
There was a problem hiding this comment.
we would need to use verbatim_doc_comment for every comment, so that --help shows something readable. As the raw text will be displayed in the terminal we will need to decide how much markdown we accept in here.
|
This is definetly the way forward, but I think we should fork/vendor the implementation and make sure we can split up the document a little more. |
|
@ruben-arts would indenting sub-commands in that single page markdown be enough? or generating separate pages is a must? |
|
@ruben-arts I have matched current CLI.md indentation levels. let me know if this is okay? |
olivier-lacroix
force-pushed
the
feat/autodoc
branch
from
1ed6765 to
c630244
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #3022
This uses the
clap-markdowncrate to generate the CLI doc. As it stands, the documentation is on a single page, with no indentation for subcommands. Would you be happy to live with the default layout ofclap-markdown?Otherwise, we could either vendor the code or add more configuration options upstream.
Would need to happen next: