I've been solving so many documentation problems with @nedbat's cog tool recently - it's fantastic for keeping documentation automatically up-to-date, in Markdown or rST)
Here's a new page of sqlite-utils docs showing --help for every CLI command! sqlite-utils.datasette.io/en/latest/cli-…
And here's how it works - I have a cog code block embedded in the .rst file which iterates through the commands and calls --help on each one, then writes the output to the page:
github.com/simonw/sqlite-…
Final trick: my GitHub Actions test.yml file calls "cog --check docs/*.rst" to confirm that the cog scripts have been run
If the test fails, I can run "cog -r docs/*.rst" to execute them, then commit the result. github.com/simonw/sqlite-…
Wrote about this trick in this TIL til.simonwillison.net/python/cog-to-…
The neat thing about having a page of your documentation that shows the output of --help is that the revision history of that page doubles as the revision history of that utility's --help github.com/simonw/sqlite-…
Just added a similar page to the documentation for Datasette, showing the output of --help for the various CLI commands: docs.datasette.io/en/latest/cli-…
The implementation for this one is simpler than the sqlite-utils version: github.com/simonw/dataset…
Share this Scrolly Tale with your friends.
A Scrolly Tale is a new way to read Twitter threads with a more visually immersive experience.
Discover more beautiful Scrolly Tales like this.