run-carbon-cli

Development work in progress

Run carbon-now-cli, in a Docker container, automated with a Python script, to create code images when files containing source code snippets are changed.

---

Example code image, created by carbon-now.

---

Requirements

This application was developed on Linux. The base requirements are Docker and Python.

It is recommended to use a Virtual Environment to separate Python package installations between different projects and your operating system's Python packages.

Initial setup. Run in the project's base directory:

# Create a Python virtual environment named 'venv'
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install development requirements
pip install -r requirements-dev.txt

# Install project requirements
pip install -r requirements.txt

When returning to the project you only need to activate the virtual environment:

source venv/bin/activate

Build and Run the Docker Container

Run the following commands from the directory containing Dockerfile.

Build the image:

docker build -t py-carbon-cli .

Run the container, mounting the local project's code_files, config_files, and images subdirectories as volumes:

docker run --name crbn \
  -v $(pwd)/code_files:/app/code_files \
  -v $(pwd)/config_files:/app/config_files \
  -v $(pwd)/images:/app/images \
  -it py-carbon-cli

These are the parameters used:

• --name = Assign a name, in this case crbn, to reference the container in subsequent docker commands.
• -v = Bind mount a volume. In this case, three volumes are mounted.
  • The code_files directory has the source code snippets from which images are produced. This directory is watched for changes while the script is running.
  • The config_files directory can contain a carbon-now presets JSON file and an options file for run_carbon_cli.py.
  • The images directory is the destination for generated images.
• -it = -i (interactive) + -t (Allocate a pseudo-TTY)

When run, this opens a BASH shell. In the BASH shell, run the following to start the Python script:

python3 run_carbon_cli.py

The script will run the run_carbon() function once, then start watching for changes in the code_files directory. The run_carbon() function is called again when a file is changed.

Press ctrl+c to stop the script.

Type exit to close the BASH prompt in the container.

Configuration Files

The run_carbon_cli.py script looks for the following optional configuration files in the config_files directory:

• carbon-now.json - This file must be in the format of a carbon-now presets file. The file config-onelight-hack-png.json is an example of that format. You can explore the available attributes by running the carbon-now CLI manually using --interactive mode (see the carbon-now docs). When you run the CLI, it produces the (hidden) file .carbon-now.json in the user home directory.

• run_carbon_cli-options.txt - Currently only one option is supported: image_max_width. For example, if the file contains image_max_width = 800 then a generated image wider than 800 pixels will be scaled (resized) down to that width.

Use for a documentation project

docker run --name crbn \
  -v /home/user/DocumentationProject/code_files:/app/code_files \
  -v /home/user/DocumentationProject/config_files:/app/config_files \
  -v /home/user/DocumentationProject/images:/app/images \
  -it py-carbon-cli

This mounts the volumes pointing to subdirectories under DocumentationProject which has its own set of code and configuration files. If working on more than one project, use a different --name for each container instance. The name crbn is used in these examples, but it can be whatever you want (or you can skip the name and use the ID values assigned by Docker to reference containers).

Other Docker Commands

See running containers:

docker ps

See running and stopped containers:

docker ps -a

Stop the running container named crbn:

docker stop crbn

Start the container named crbn:

docker start crbn

Connect an interactive TTY to get the BASH prompt in the running crbn container:

docker exec -it crbn bash

Remove the stopped crbn container (must be removed before doing another build and run to incorporate changes to the script or change volume paths):

docker rm crbn

Reference

Carbon

Website: Carbon: Create and share beautiful images of your source code

GitHub: carbon-app/carbon: Create and share beautiful images of your source code

GitHub: mixn/carbon-now-cli: Beautiful images of your code — from right inside your terminal.

Project Tools

• Docker - Create, manage, and run containers

  • The Official Python image is used as the base image in the Dockerfile

• Ruff - Python code linter and formatter

Python Packages Used

• pillow - Python Imaging Library fork

  • Pillow documentation: Image.resize
  • Pillow documentation: Concepts - filters

• rich - add color and style to terminal output

• watchfiles - file watching and code reload in python

Additional Links

Python Packaging User Guide: Install packages in a virtual environment using pip and venv

Docker Docs: Volumes

Dan Wahlin - Code with Dan Blog: Docker Volumes and “print working directory” Command Syntax