https://github.com/reecepbcups/docci
Your documentation is now your test suite
https://github.com/reecepbcups/docci
ci documentation integration-testing
Last synced: about 1 year ago
JSON representation
Your documentation is now your test suite
- Host: GitHub
- URL: https://github.com/reecepbcups/docci
- Owner: Reecepbcups
- License: apache-2.0
- Created: 2025-03-16T01:51:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-17T00:19:25.000Z (about 1 year ago)
- Last Synced: 2025-03-17T00:23:14.621Z (about 1 year ago)
- Topics: ci, documentation, integration-testing
- Language: Python
- Homepage:
- Size: 67.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docci | Readme Runner 🚀 · [](https://github.com/Reecepbcups/docci/blob/main/LICENSE) [](https://github.com/Reecepbcups/docci/actions/workflows/test.yml) [](https://github.com/Reecepbcups/docci)
Your documentation is now your test suite! 🎯 *(pronounced "doc-ee", short for documentation CI)*
A CI tool that brings your markdown docs to life by executing code blocks in sequence. Run processes in the background, handle environment variables, add delays, verify outputs, and modify files - all through simple markdown tags. Perfect for ensuring your docs stay accurate and your examples actually work! 📚
## 🏃♂️ Quick Start
Find sample workspaces in the [`examples/` directory](./examples/).
### 📦 Installation
````bash
make install
````
### 🤖 Github Actions Integration
````yaml
# update the version in the URL
# update the config path argument
- name: Docci Readme Runner
run: |
sudo wget -O /usr/local/bin/docci https://github.com/Reecepbcups/docci/releases/download/v0.4.1/docci
sudo chmod +x /usr/local/bin/docci
docci .github/workflows/config.json
````
### 🎮 Usage
```bash docci-ignore
docci
# e.g. docci .github/workflows/config.json
# e.g. docci '{"paths": ["docs/README.md"],"working_dir": "docs/","cleanup_cmds": ["kill -9 $(lsof -t -i:3000)"]}'
```
### 🎨 Operation tags
* 🛑 `docci-ignore`: Skip executing this code block
* 🔄 `docci-background`: Run the command in the background
* 🚫 `docci-if-not-installed=BINARY`: Skip execution if some binary is installed (e.g. node)
* ⏲️ `docci-delay-after=N`: Wait N seconds after running commands
* ⌛ `docci-delay-per-cmd=N`: Wait N seconds before each command
* 🌐 `docci-wait-for-endpoint=http://localhost:8080/health|N`: Wait up to N seconds for the endpoint to be ready
* 📜 `docci-output-contains="string"`: Ensure the output contains a string at the end of the block
* 🚨 `docci-assert-failure`: If it is expected to fail (non 0 exit code)
* 🖥️ `docci-os=mac|linux`: Run the command only on it's the specified OS
### 📄 File Tags
* `docci-file`: The file name to operate on
* `docci-reset-file`: Reset the file to its original content
* `docci-line-insert=N`: Insert content at line N
* `docci-line-replace=N`: Replace content at line N
* `docci-line-replace=N-M`: Replace content from line N to M
### 💡 Code Block Tag Examples (Operations)
Skip needless installations if you are already set up: 🛑
````bash
```bash docci-os=linux docci-if-not-installed=node
# this only runs if `node` is not found in the system & it's a linux system
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
export NVM_DIR="$HOME/.nvm"
nvm install v21.7.3
```
````
Ensure the output contains a specific string: 📜
````bash
# This checks stdout and stderr
```bash docci-output-contains="xyzMyOutput"
echo xyzMyOutput
```
````
Run blocking commands in the background with delays: 🌐
````bash
```bash docci-background docci-delay-after=5
cp .env.example .env
EXAMPLE_PORT=3000 make my-long-running-process
# waits 5 seconds here
```
````
Add delays between commands for stability after the endpoint from a previous command is up: ⏱️
````bash
```bash docci-delay-per-cmd=1 docci-wait-for-endpoint=http://localhost:8080|30
go run save_large_file_from_endpoint.go http://localhost:8080/my-endpoint
# waits 1 second
cat my-file.txt
# waits 1 second
```
````
Assert that a command fails: 🚨
````bash
```bash docci-assert-failure
notinstalledbin --version
```
````
### 💡 Code Block Tag Examples (Files)
Create a new file from content: 📝
````html
```html docci-file=example.html docci-reset-file
My Titlee
```
````
Replace the typo'ed line:
````html
```html docci-file=example.html docci-line-replace=3
My Title
```
````
Add new content
````html
```html docci-file=example.html docci-line-insert=4
My Header
1 paragraph
2 paragraph
```
````
Replace multiple lines
````html
```html docci-file=example.html docci-line-replace=7-9
First paragraph
Second paragraph
```
````
## 🛠️ How It Works
The tool processes markdown files and executes code blocks based on configuration settings. The core workflow is handled by several key components:
1. 📋 **Configuration Loading** (`config_types.py`): Loads and validates the JSON configuration file
2. 📝 **Markdown Processing** (`main.py`): Parses markdown files and processes code blocks
3. ⚡ **Command Execution** (`execute.py`): Handles command execution and env vars
4. 🎯 **Tag Processing** (`models.py`): Manages execution control tags
Control how your documentation code blocks are executed with no code, just code block tags. 🏷️
## ⚙️ JSON Configuration Options
- 📂 `paths`: List of markdown files or directories to process (required)
- 🔐 `env_vars`: Environment variables to set during execution
- 🎬 `pre_cmds`: Commands to run before processing markdown
- 🧹 `cleanup_cmds`: Commands to run after processing
- 📂 `working_dir`: Working directory for command execution
### 📝 Config Example
````json
{
"paths": ["docs/README.md"],
"env_vars": {
"NODE_ENV": "test"
},
"working_dir": "docs/",
"debugging": false,
"pre_cmds": ["npm install"],
"cleanup_cmds": ["docker-compose down"],
}
````
## 🚧 Limitations
- Not yet tested on Windows WSL, but should work.
- Multi-line commands in docs are not supported yet