Repository navigation
Way to render CLI usage examples in docstrings #2762
Description
Is there an easy way to define CLI usage examples, and display them in a noticeable way (let's say in bold output)? This could either be inline inside the main docstring, like this:
def main(foo):
"""Run the program.
Do some stuff
Run program with flag foo
`./program.py --foo`
(where the bit in backticks would get rendered in bold or something)
or via some kind of @click.usage or @click.example decorator?
Activity
davidism commentedon Aug 9, 2024
https://sphinx-click.readthedocs.io/en/latest/
wyardley commentedon Aug 9, 2024
@davidism I'm normally familiar with Sphinx for web-based / html docs -- will this work for the inline docs (via
./command --helpetc.)? Is there an example of how a usage example would be defined?Also, sorry if I'm being obtuse, but based on the docs above, I couldn't find a specific way of including command examples via, say, a decorator, or extracting them from the help text.
My goal is to be able to have usage examples (of how the program and its flags are to be used) in the inline console based docs.
davidism commentedon Aug 9, 2024
You would write them in the docstring, which gets turned into the command description.