| Name | rich-codex JSON |
| Version |
1.2.7
JSON |
| download |
| home_page | https://github.com/ewels/rich-codex |
| Summary | Generate rich images for the GitHub Action 'rich-codex' |
| upload_time | 2024-01-23 22:30:02 |
| maintainer | Phil Ewels |
| docs_url | None |
| author | Phil Ewels |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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/ 📚
[](https://pypi.python.org/pypi/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
1. 📖 Write some markdown docs, use an image tag with a backtick command inside:
<!-- RICH-CODEX {terminal_width: 120, notrim: true} -->
```markdown
```
2. 🤖 Add a GitHub Action to automatically run the command, generate the image and commit to the repo:
```yaml
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 
## How it works
Rich-codex is a command-line tool that you can run [via a GitHub action](https://ewels.github.io/rich-codex/installation/github_action/) or as a [command line tool](https://ewels.github.io/rich-codex/installation/cli/). 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](https://github.com/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](https://github.com).
Rich-codex needs **inputs** (commands / snippets) and **output filenames** to work. These can be configured in four different ways:
- 🖼 [Markdown images](https://ewels.github.io/rich-codex/inputs/markdown/)
- Search markdown files for image tags with command alt text. eg: ``  ``
- 💬 [Markdown comments](https://ewels.github.io/rich-codex/inputs/markdown/#code-snippets)
- Search markdown files for special HTML comments.
- ➡️ [Command-line / action inputs](https://ewels.github.io/rich-codex/inputs/direct_inputs/)
- Specify a command or snippet using the action `with` inputs.
- ⚙️ [Config files](https://ewels.github.io/rich-codex/inputs/config_file/)
- 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/
Raw data
{
"_id": null,
"home_page": "https://github.com/ewels/rich-codex",
"name": "rich-codex",
"maintainer": "Phil Ewels",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "phil@ewels.co.uk",
"keywords": "",
"author": "Phil Ewels",
"author_email": "phil@ewels.co.uk",
"download_url": "https://files.pythonhosted.org/packages/cb/a5/c6b9c186068f34e23ae7c871f9ae405de3153090429ead490f34abcd7ce0/rich-codex-1.2.7.tar.gz",
"platform": null,
"description": "# rich-codex \u26a1\ufe0f\ud83d\udcd6\u26a1\ufe0f\n\nA GitHub Action / command-line tool which generates screengrab images of a terminal window, containing _command outputs_ or _code snippets_.\n\n## \ud83d\udcda Documentation: https://ewels.github.io/rich-codex/ \ud83d\udcda\n\n[](https://pypi.python.org/pypi/rich-codex/)\n\n## Introduction\n\nHaving code examples in your documentation is a fantastic way to help users understand what to expect from your tool.\n\nUsing terminal screenshots is a good way to do this because:\n\n- \ud83c\udf08 Coloured terminal output is supported\n- \u2194\ufe0f You can fit in long lines without scrolling or cropping (images are auto-resized)\n- \ud83d\ude0e They look cool\n\nHowever, manually generating these screenshots is a pain \ud83d\udc4e\ud83c\udffb Remembering to update them every time you make a minor change means that they can easily get out of date.\n\n_**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.\n\nTypical use cases:\n\n- \ud83d\udcf7 Example CLI tool outputs that _automatically stay in sync with your package_\n- \u267b\ufe0f Syntax-highlighted code snippets that are always up to date with your `examples/`\n- \ud83e\udd29 Fast and simple images for your docs with minimal setup\n\n## Quickstart\n\n1. \ud83d\udcd6 Write some markdown docs, use an image tag with a backtick command inside:\n <!-- RICH-CODEX {terminal_width: 120, notrim: true} -->\n ```markdown\n \n ```\n2. \ud83e\udd16 Add a GitHub Action to automatically run the command, generate the image and commit to the repo:\n\n ```yaml\n on: [push]\n jobs:\n rich_codex:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n - name: Install your custom tools\n run: pip install lolcat\n\n - name: Generate terminal images with rich-codex\n uses: ewels/rich-codex@v1\n with:\n commit_changes: \"true\"\n ```\n\n3. \ud83c\udf08 Enjoy reading your documentation \n\n## How it works\n\nRich-codex is a command-line tool that you can run [via a GitHub action](https://ewels.github.io/rich-codex/installation/github_action/) or as a [command line tool](https://ewels.github.io/rich-codex/installation/cli/). It works with any markdown (including GitHub READMEs).\n\nIt 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](https://github.com/textualize/rich).\n\n> 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](https://github.com).\n\nRich-codex needs **inputs** (commands / snippets) and **output filenames** to work. These can be configured in four different ways:\n\n- \ud83d\uddbc [Markdown images](https://ewels.github.io/rich-codex/inputs/markdown/)\n - Search markdown files for image tags with command alt text. eg: ``  ``\n- \ud83d\udcac [Markdown comments](https://ewels.github.io/rich-codex/inputs/markdown/#code-snippets)\n - Search markdown files for special HTML comments.\n- \u27a1\ufe0f [Command-line / action inputs](https://ewels.github.io/rich-codex/inputs/direct_inputs/)\n - Specify a command or snippet using the action `with` inputs.\n- \u2699\ufe0f [Config files](https://ewels.github.io/rich-codex/inputs/config_file/)\n - Use one or more YAML config files for multiple images and more complex customisation.\n\nImages can be generated as SVG, PNG or PDF (detected by filename extension).\n\n> **Keep reading!** \ud83d\udc49 https://ewels.github.io/rich-codex/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate rich images for the GitHub Action 'rich-codex'",
"version": "1.2.7",
"project_urls": {
"Documentation": "https://github.com/ewels/rich-codex",
"Homepage": "https://github.com/ewels/rich-codex",
"Issue Tracker": "https://github.com/ewels/rich-codex/issues/",
"Source Code": "https://github.com/ewels/rich-codex"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c9a15ab0dea30088e03e5e65f65f56e64a078caa797d14801b101ff53840e26a",
"md5": "59224ea9de099635c819316921a435df",
"sha256": "d0a360d21e15736bbaef6ed45aab62a5859045a1c83296cf440fa3778f269029"
},
"downloads": -1,
"filename": "rich_codex-1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59224ea9de099635c819316921a435df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22734,
"upload_time": "2024-01-23T22:30:00",
"upload_time_iso_8601": "2024-01-23T22:30:00.905482Z",
"url": "https://files.pythonhosted.org/packages/c9/a1/5ab0dea30088e03e5e65f65f56e64a078caa797d14801b101ff53840e26a/rich_codex-1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cba5c6b9c186068f34e23ae7c871f9ae405de3153090429ead490f34abcd7ce0",
"md5": "36a794bd21aac6dd7857c2c2a78fa454",
"sha256": "68e29dfcf56285a618a2ca50b4447aafb5f2ae38bd73a99bdc1e4c6700e56335"
},
"downloads": -1,
"filename": "rich-codex-1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "36a794bd21aac6dd7857c2c2a78fa454",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22473,
"upload_time": "2024-01-23T22:30:02",
"upload_time_iso_8601": "2024-01-23T22:30:02.796800Z",
"url": "https://files.pythonhosted.org/packages/cb/a5/c6b9c186068f34e23ae7c871f9ae405de3153090429ead490f34abcd7ce0/rich-codex-1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-23 22:30:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ewels",
"github_project": "rich-codex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rich-codex"
}
