The library is in its early stages!
:::{admonition} TL;DR :class: note
- 🎥 Record interactions (input & output) with CLI applications
- 🤖 Automate the recording process via simple Sphinx directives
- ✔️ Simple; does not require any knowledge of the underlying recording application
- ⛓️ No dependencies on external services; all files are generated and hosted locally :::
This Sphinx extension is a tool to allow you to easily automate the recording process of CLI applications (without you having to leave your editor 🤯).
Suppose you are developing a neat CLI application, possibly with rich (get it?) visual output. In that case, you put blood, sweat, and tears into the development part but do you want to put the same amount of effort into the documentation? Shouldn't it be easy to show what your CLI application can do? If you record a terminal session to show how to interact with your tool, you need to ensure that the recording is kept up-to-date and doesn't break with future updates. Then you need to know how to upload the file and embed it into your documentation. And all you want to do is to show something cool like:
:autoplay: "True"
Or give the user an example on how to navigate your CLI application:
- "y"
- "5"
- "2"
- "poodle"
- "husky"
Or you are looking for a simple way always to include the most recent help text of a tool you are developing.
:rows: 67
:autoplay: "True"
In those cases, it is probably easier to let the Sphinx-CLI-Recorder handle it for you. 😎 It uses asciinema, a text-based terminal recorder under the hood. Utilizing a text-based terminal player has the following advantages:
- ✅ The output is lossless; no more pixelated videos/images with compression artifacts
- ✅ No need to wait for huge-video file downloads
- ✅ The terminal's content can be copied to the clipboard; no need to manually re-type the commands that are shown in a GIF/video
The benefits of using this Sphinx extension are:
- 🤖 Automates the recording process of asciinema
- 📅 Ensures that the recordings are always up-to-date
- 💣 If the code changes and the commands from the documentation fail, no documentation will be built
- 🏠 Keeps all of your files/data local:
- 🔐 No need to depend on external services/tokens to upload the recordings
- 🚅 The recordings are done in parallel to minimize the documentation build time
- ☑️ Simple; no need to understand how asciinema works