Generate rich images for the GitHub Action 'rich-codex'
Project description
rich-codex ⚡️📖⚡️
A GitHub Action / command-line tool which generates screengrab images of a terminal window, containing command outputs or code snippets.
📚 Documentation: https://ewels.github.io/rich-codex/ 📚
Introduction
Having code examples in your documentation is a fantastic way to help users understand what to expect from your tool.
Using terminal screenshots is a good way to do this because:
- 🌈 Coloured terminal output is supported
- ↔️ You can fit in long lines without scrolling or cropping (images are auto-resized)
- 😎 They look cool
However, manually generating these screenshots is a pain 👎🏻 Remembering to update them every time you make a minor change means that they can easily get out of date.
Rich-codex automates this process for you. It searches markdown code for images with shell commands or code snippets. It runs these commands and saves a terminal screen-grab at the embedded path.
Typical use cases:
- 📷 Example CLI tool outputs that automatically stay in sync with your package
- ♻️ Syntax-highlighted code snippets that are always up to date with your
examples/
- 🤩 Fast and simple images for your docs with minimal setup
Quickstart
-
📖 Write some markdown docs, use an image tag with a backtick command inside:
![`cat docs/cat.txt | lolcat -S 1`](docs/img/cat.png)
-
🤖 Add a GitHub Action to automatically run the command, generate the image and commit to the repo:
on: [push] jobs: rich_codex: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install your custom tools run: pip install lolcat - name: Generate terminal images with rich-codex uses: ewels/rich-codex@v1 with: commit_changes: "true"
-
🌈 Enjoy reading your documentation
How it works
Rich-codex is a command-line tool that you can run via a GitHub action or as a command line tool. It works with any markdown (including GitHub READMEs).
It collects either commands or code snippets, together with output filenames and configuration options. Commands are run in a subprocess and the standard output & standard error collected. These are then rendered as an image using Textualize/rich.
Rich-codex creates the images that your markdown docs expect. It doesn't require a HTML build-step and doesn't make any changes to your markdown or its output. As such, it's compatible with any documentation engine, including rendering markdown on github.com.
Rich-codex needs inputs (commands / snippets) and output filenames to work. These can be configured in four different ways:
- 🖼 Markdown images
- Search markdown files for image tags with command alt text. eg:
![`rich-codex --help`](docs/img/rich-codex-help.svg)
- Search markdown files for image tags with command alt text. eg:
- 💬 Markdown comments
- Search markdown files for special HTML comments.
- ➡️ Command-line / action inputs
- Specify a command or snippet using the action
with
inputs.
- Specify a command or snippet using the action
- ⚙️ Config files
- Use one or more YAML config files for multiple images and more complex customisation.
Images can be generated as SVG, PNG or PDF (detected by filename extension).
Keep reading! 👉 https://ewels.github.io/rich-codex/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for rich_codex-1.2.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d0a360d21e15736bbaef6ed45aab62a5859045a1c83296cf440fa3778f269029 |
|
MD5 | 59224ea9de099635c819316921a435df |
|
BLAKE2b-256 | c9a15ab0dea30088e03e5e65f65f56e64a078caa797d14801b101ff53840e26a |