3 ms·
I discovered Cog a couple of years ago and I use it on dozens of my own projects now. It's a really neat thing to have around. One trick I use a lot is includi
by simonw 3y ago
I discovered Cog a couple of years ago and I use it on dozens of my own projects now. It's a really neat thing to have around.
One trick I use a lot is including the output of the "--help" command in the README files for CLI tools that I release.
Here's an example: https://github.com/simonw/ospeak/blob/main/README.md#ospeak---help https://github.com/simonw/ospeak/blob/main/README.md#ospeak-...
View source on that file and you'll see this:
## ospeak --help
<!-- [[[cog
import cog
from ospeak import cli
from click.testing import CliRunner
runner = CliRunner()
result = runner.invoke(cli.cli, ["--help"])
help = result.output.replace("Usage: cli", "Usage: ospeak")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: ospeak [OPTIONS] [TEXT]
CLI tool for running text through OpenAI Text to speech
Set the OPENAI_API_KEY environment variable to your OpenAI API key to avoid
using the --token option every time.
Example usage:
ospeak "Everyone deserves a pelican" --voice alloy -x 1.5
Options:
--version Show the version and exit.
-v, --voice [alloy|echo|fable|onyx|nova|shimmer|all]
Voice to use
-o, --output FILE Save audio to this file on disk
-x, --speed FLOAT RANGE Speed of the voice [0.25<=x<=4.0]
-s, --speak Speak the text even when saving to a file
--token TEXT OpenAI API key
--help Show this message and exit.
```
<!-- [[[end]]] -->
I can now run "cog -r README.md" any time I want to update that block of text in the README.
I also have this line in my GitHub Actions test.yml workflow: https://github.com/simonw/ospeak/blob/73a449d3f006737e72e7a0c5ae47516d7ede766e/.github/workflows/test.yml#L29 https://github.com/simonw/ospeak/blob/73a449d3f006737e72e7a0...
cog --check README.md
That way my tests will fail if I make a change to the help and forget to update the README.
I like reflecting my help output in my documentation mainly because it's a useful way to review if the help makes sense without having to actually run the command.
I maintain these much larger pages using Cog in a similar way:
- https://docs.datasette.io/en/stable/cli-reference.html https://docs.datasette.io/en/stable/cli-reference.html
- https://sqlite-utils.datasette.io/en/stable/cli-reference.html https://sqlite-utils.datasette.io/en/stable/cli-reference.ht...
- https://llm.datasette.io/en/stable/help.html https://llm.datasette.io/en/stable/help.html
I wrote a bit more about this pattern here: https://til.simonwillison.net/python/cog-to-update-help-in-readme https://til.simonwillison.net/python/cog-to-update-help-in-r...
- lifeisstillgood 3y agoOk, just wanted to say I had no idea click.CLIRunner was a thing - going to try that today for my own test suite but this shows me a style Indid wonder about - cog is importing other python code (inside the package?) to do its thing. Makes more sense than attaching to C++ code I think
- sco1 3y ago+1 for enumerating CLI options in markdown files. I commonly forget to update my READMEs when making changes to the interface and cog has been a really helpful utility to take care of this for me. I include this pattern in pretty much every tool I make nowadays, honestly probably inspired by your blog post on the topic :) This year I also realized I could use it for my Advent of Code repository to sync my yearly progress tracker with a summary table in the base directory's README: https://github.com/sco1/adventofcode/commit/9b14483fc3d9ef589273ca3d48b1da55f310c9d3 https://github.com/sco1/adventofcode/commit/9b14483fc3d9ef58... .