Way to render CLI usage examples in docstrings

[wyardley]

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?

[davidism]

https://sphinx-click.readthedocs.io/en/latest/

[wyardley]

@davidism I'm normally familiar with Sphinx for web-based / html docs -- will this work for the inline docs (via ./command --help etc.)? 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]

You would write them in the docstring, which gets turned into the command description.

[wyardley]

Right, that part I totally get and is working as expected. But I couldn't find in the docs any simple way to render portions in bold or bright text without using raw escape characters? That could be treating text between backticks / triple-backticks differently, a la markdown, or some other way of marking it.

I don't think click.style() will work in here, and I didn't find an exhaustive list of escape markers.

I can get something roughly like what I want (each command on a line, but not with extra newlines between, and bright) like this (by making the output bright white and disabling line wrap)

    \b
    Examples:
      \033[1m./foo.py --filename xyz.txt\033[0m
      \033[1mecho "foo" | ./foo.py\033[0m
      \033[1m./foo.py < xyz.txt\033[0m

it's just kind of hard to read in the code.

Similarly, it would be nice to be able to keep the auto-wrapping, but have newlines between examples without a blank line... for now, using the \b escape marker around the whole block seems to work Ok, though it might cause issues with a long example command and a very narrow terminal.

Since it's all obviously already fixed text, I'm just trying to find ways to make it stand out a bit more; using quotes around it might work, but would be a bit confusing for commands that have quotes in them.

Anyway, long term, would be cool if there was another top level section called Examples (similar to Usage / Options) that would include examples from @click.example decorator blocks, but I think I can make something work as-is, just wanted to see if there was an easier way.