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

介绍

在您的文档中包含代码示例是帮助用户了解您的工具的一种绝佳方式。

使用终端屏幕截图是这样做的好方法，因为

• 🌈 支持彩色终端输出
• ↔️ 您可以容纳长行而无需滚动或裁剪（图像自动缩放）
• 😎 它们看起来很酷

然而，手动生成这些截图是一个痛苦的过程 👎🏻 记得在每次进行小的更改时更新它们，否则它们很容易过时。

Rich-codex 为您自动化了这个过程。它搜索Markdown代码中的带有shell命令或代码片段的图像。它运行这些命令，并在嵌入式路径中保存终端屏幕截图。

典型用例

• 📷 自动与您的软件包保持同步的示例CLI工具输出
• ♻️ 与您的examples/目录始终保持更新的语法高亮代码片段
• 🤩 最小配置即可快速简单的生成文档中的图像

快速入门

1. 📖 编写一些Markdown文档，使用带有反引号的命令的内联图像标签

   ![`cat docs/cat.txt | lolcat -S 1`](docs/img/cat.png)
   

2. 🤖 添加 GitHub Action 以自动运行命令、生成图像并将其提交到仓库

   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. 🌈 喜欢阅读您的文档

工作原理

Rich-codex 是一个命令行工具，您可以通过 GitHub Action 或作为 命令行工具 来运行。它与任何 markdown（包括 GitHub READMEs）兼容。

它收集命令或代码片段，以及输出文件名和配置选项。命令在子进程中运行，标准输出和标准错误被收集。然后使用 Textualize/rich 将其渲染为图像。

Rich-codex 创建了 markdown 文档所期望的图像。它不需要 HTML 构建步骤，也不会对 markdown 或其输出进行任何更改。因此，它与 任何文档引擎 兼容，包括在 github.com 上渲染 markdown。

Rich-codex 需要输入（命令/片段）和 输出文件名 才能工作。这些可以通过四种不同的方式配置

• 🖼 Markdown 图像
  • 在 markdown 文件中搜索具有命令 alt 文本的图像标签。例如：![`rich-codex --help`](docs/img/rich-codex-help.svg)
• 💬 Markdown 注释
  • 在 markdown 文件中搜索特殊的 HTML 注释。
• ➡️ 命令行/操作输入
  • 使用操作的 with 输入指定命令或片段。
• ⚙️ 配置文件
  • 使用一个或多个 YAML 配置文件来配置多个图像和更复杂的自定义。

图像可以生成为 SVG、PNG 或 PDF（由文件扩展名检测）。

继续阅读！ 👉 https://ewels.github.io/rich-codex/