4 ms·
> The README is using a trick I'm increasingly leaning on: parts of that document - the --help output and the example database schema - are automatically genera
by samhw 5y ago
> The README is using a trick I'm increasingly leaning on: parts of that document - the --help output and the example database schema - are automatically generated using Cog
How does this interact with IDEs? Has anyone written a VSCode extension yet? I'd probably be reluctant to use something like this without IDE support. (Though I may well be in the minority, and I appreciate that for open source tools it's not necessarily reasonable to expect people to dedicate so much of their time to DX.)
- simonw 5y agoTo regenerate the markdown file I run this command in the console: cog -r README.md Presumably most IDEs have q mechanism that can run that command automatically, either when a file changes or just intermittently over time. I use VS Code's markdown preview panel, which updates automatically when I manually run the "cog -r" command.
- ash 5y agoNice! I didn't know about cog. I've developed a simple "codeblocks" tool that to keep README.md up-to-date. In your example, here is how to insert the latest `--help` output: codeblocks usage-auth README.md -- google-drive-to-sqlite auth --help Where "usage-auth" is the block language in README.md: Full `--help`: ```usage-auth Usage: ... ``` Checking is also possible: codeblocks --check usage-auth README.md -- google-drive-to-sqlite auth --help It's not as generic as cog, but does not require writing codegen scripts inside Markdown file. https://github.com/shamrin/codeblocks https://github.com/shamrin/codeblocks
- whateveracct 5y agohm I'm guessing..run the cog command in the VSCode terminal
- _hl_ 5y agoNotable alternative for emacs users: Github supports rendering .org files, so you can have a README.org using babel (just remember to execute all code blocks before pushing).