Repository navigation
Add Screenshot workflow #3081
Description
Activity
I'm not clear why we need screenshots for this? Code and CLI invocations are entirely text based. This would add a huge amount of complexity to our docs builds.
If you want to call out certain lines in a block of text, you can do that with Sphinx already: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-code-block-emphasize-lines
It's definitely not a need. More of it would be very nice. See the attached screenshot. The best way I can think to give an overview for a help page if you are unfamiliar with command line help pages would be to show a lot on a help page and box and label it. Gives a very nice overview.
There are a few other places, I had in mind to use it.
I was planning on looking at the options and seeing. An option might be nothing is worth it.
- draw boxes around various sections.
I guess you want to do what @janluke did to highlight the different parts of the help screen in Cloup:
Source: https://cloup.readthedocs.io/en/stable/pages/formatting.html#themes
Yes. I have never seen this, but I was thinking this exactly.
Another requirement: This must not pull in any external dependencies/build dependencies. Users and contributors need to be able to build the docs without more overhead.
The easiest way here is to take a screenshot and edit it.
I assume fine as long as pip installable?
As long as it's pip installable without requiring external things like imagemagick being installed on the system.
@pdonizete It looks like you used some (broken) LLM to generate this comment considering the raw
\nlinebreaks in there that a human would not write... We are not interested in AI-generated contributions. So if you wish to use LLMs for this, please find another project to contribute to.I am taking this.
Reacted by Alex Koster1 remaining item
Drafted PR: #3472
I will add the annotated screenshot to the PR as well.
In talking with @saxenanurag, best to just manually annotate a screen shot nicely.
- linked a pull request that will close this issueAdd example for Group Help Page in documentation #3472
on May 22, 2026 - removed a link to a pull requestAdd example for Group Help Page in documentation #3472
on May 23, 2026 @Rowlando13 I made an inventory of CLI screenshot solutions in https://kdeldycke.github.io/click-extra/screenshots.html . I did not settled on one yet but will test drive them in the next few months.
Nice!
I went the extra mile and you can now produce SVG screenshots of CLIs with Click Extra with a one-liner. No need to install it thanks to
uvx.Here is an example of calling
flaskand rendering a simulation of its invocation in a macOS-like terminal and highlighted lines:$ uvx --with flask click-extra screenshot --output flask-help.svg --preset macos --emphasize-lines 2,10,24 --wrap -- flask --helpWhich renders to:
That is cool! I only planned to add a few screenshots for help pages, but I was concerned about increasing the package size. SVG could fix that.
In a few places in the docs, it would be really nice to be able to run some code take a screen shot, and draw boxes around different parts. For example setup an example click app with multiple sub commands, options, epilog help, and arguments and then draw boxes and label the various blocks. Requirements:
Conduct some research and propose some options. A maintainer will pick from the options. and you can implement it. Here is an example of what I was thinking is in the comments below.