Skip to main content

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/ 📚

PyPI Version

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

  1. 📖 Write some markdown docs, use an image tag with a backtick command inside:

    ![`cat docs/cat.txt | lolcat -S 1`](docs/img/cat.png)
    
  2. 🤖 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"
    
  3. 🌈 Enjoy reading your documentation My cat rainbow

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)
  • 💬 Markdown comments
    • Search markdown files for special HTML comments.
  • ➡️ Command-line / action inputs
    • Specify a command or snippet using the action with inputs.
  • ⚙️ 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rich-codex-1.2.7.tar.gz (22.5 kB view hashes)

Uploaded Source

Built Distribution

rich_codex-1.2.7-py3-none-any.whl (22.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page