{"id":26485188,"url":"https://github.com/reecepbcups/docci","last_synced_at":"2025-03-20T05:55:44.104Z","repository":{"id":282787890,"uuid":"949241772","full_name":"Reecepbcups/docci","owner":"Reecepbcups","description":"Your documentation is now your test suite","archived":false,"fork":false,"pushed_at":"2025-03-17T00:19:25.000Z","size":69,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T00:23:14.621Z","etag":null,"topics":["ci","documentation","integration-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Reecepbcups.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-16T01:51:32.000Z","updated_at":"2025-03-16T23:11:28.000Z","dependencies_parsed_at":"2025-03-17T04:45:49.641Z","dependency_job_id":null,"html_url":"https://github.com/Reecepbcups/docci","commit_stats":null,"previous_names":["reecepbcups/docci"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Reecepbcups","download_url":"https://codeload.github.com/Reecepbcups/docci/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244560351,"owners_count":20472219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","documentation","integration-testing"],"created_at":"2025-03-20T05:55:43.713Z","updated_at":"2025-03-20T05:55:44.093Z","avatar_url":"https://github.com/Reecepbcups.png","language":"Python","readme":"# Docci | Readme Runner 🚀 \u0026middot; [![GitHub license](https://img.shields.io/badge/license-apache-blue.svg)](https://github.com/Reecepbcups/docci/blob/main/LICENSE) [![Tests](https://github.com/Reecepbcups/docci/actions/workflows/test.yml/badge.svg)](https://github.com/Reecepbcups/docci/actions/workflows/test.yml) [![Compatible](https://img.shields.io/badge/compatible%20-macOS_\u0026_linux-8A2BE2.svg)](https://github.com/Reecepbcups/docci)\n\nYour documentation is now your test suite! 🎯 *(pronounced \"doc-ee\", short for documentation CI)*\n\nA 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! 📚\n\n## 🏃‍♂️ Quick Start\n\nFind sample workspaces in the [`examples/` directory](./examples/).\n\n### 📦 Installation\n\n````bash\nmake install\n````\n\n### 🤖 Github Actions Integration\n````yaml\n# update the version in the URL\n# update the config path argument\n- name: Docci Readme Runner\n    run: |\n    sudo wget -O /usr/local/bin/docci https://github.com/Reecepbcups/docci/releases/download/v0.4.1/docci\n    sudo chmod +x /usr/local/bin/docci\n    docci .github/workflows/config.json\n````\n\n### 🎮 Usage\n\n```bash docci-ignore\ndocci \u003cconfig_path | config_json\u003e\n# e.g. docci .github/workflows/config.json\n# e.g. docci '{\"paths\": [\"docs/README.md\"],\"working_dir\": \"docs/\",\"cleanup_cmds\": [\"kill -9 $(lsof -t -i:3000)\"]}'\n```\n\n### 🎨 Operation tags\n  * 🛑 `docci-ignore`: Skip executing this code block\n  * 🔄 `docci-background`: Run the command in the background\n  * 🚫 `docci-if-not-installed=BINARY`: Skip execution if some binary is installed (e.g. node)\n  * ⏲️ `docci-delay-after=N`: Wait N seconds after running commands\n  * ⌛ `docci-delay-per-cmd=N`: Wait N seconds before each command\n  * 🌐 `docci-wait-for-endpoint=http://localhost:8080/health|N`: Wait up to N seconds for the endpoint to be ready\n  * 📜 `docci-output-contains=\"string\"`: Ensure the output contains a string at the end of the block\n  * 🚨 `docci-assert-failure`: If it is expected to fail (non 0 exit code)\n  * 🖥️ `docci-os=mac|linux`: Run the command only on it's the specified OS\n\n### 📄 File Tags\n  * `docci-file`: The file name to operate on\n  * `docci-reset-file`: Reset the file to its original content\n  * `docci-line-insert=N`: Insert content at line N\n  * `docci-line-replace=N`: Replace content at line N\n  * `docci-line-replace=N-M`: Replace content from line N to M\n\n### 💡 Code Block Tag Examples (Operations)\n\nSkip needless installations if you are already set up: 🛑\n\n\u003c!-- The 4 backticks is just so it wraps in githubs UI, real test are written normally with the nested part (just 3 backticks) --\u003e\n````bash\n```bash docci-os=linux docci-if-not-installed=node\n# this only runs if `node` is not found in the system \u0026 it's a linux system\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash\nexport NVM_DIR=\"$HOME/.nvm\"\nnvm install v21.7.3\n```\n````\n\nEnsure the output contains a specific string: 📜\n\n````bash\n# This checks stdout and stderr\n```bash docci-output-contains=\"xyzMyOutput\"\necho xyzMyOutput\n```\n````\n\nRun blocking commands in the background with delays: 🌐\n\n````bash\n```bash docci-background docci-delay-after=5\ncp .env.example .env\nEXAMPLE_PORT=3000 make my-long-running-process\n# waits 5 seconds here\n```\n````\n\nAdd delays between commands for stability after the endpoint from a previous command is up: ⏱️\n\n````bash\n```bash docci-delay-per-cmd=1 docci-wait-for-endpoint=http://localhost:8080|30\ngo run save_large_file_from_endpoint.go http://localhost:8080/my-endpoint\n# waits 1 second\ncat my-file.txt\n# waits 1 second\n```\n````\n\nAssert that a command fails: 🚨\n\n````bash\n```bash docci-assert-failure\nnotinstalledbin --version\n```\n````\n\n### 💡 Code Block Tag Examples (Files)\n\nCreate a new file from content: 📝\n\n\u003c!-- yes, the typo is meant to be here --\u003e\n````html\n```html docci-file=example.html docci-reset-file\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eMy Titlee\u003c/title\u003e\n    \u003c/head\u003e\n\u003c/html\u003e\n```\n````\n\nReplace the typo'ed line:\n\n````html\n```html docci-file=example.html docci-line-replace=3\n        \u003ctitle\u003eMy Title\u003c/title\u003e\n```\n````\n\nAdd new content\n\n````html\n```html docci-file=example.html docci-line-insert=4\n    \u003cbody\u003e\n        \u003ch1\u003eMy Header\u003c/h1\u003e\n        \u003cp\u003e1 paragraph\u003c/p\u003e\n        \u003cp\u003e2 paragraph\u003c/p\u003e\n    \u003c/body\u003e\n```\n````\n\nReplace multiple lines\n\n````html\n```html docci-file=example.html docci-line-replace=7-9\n        \u003cp\u003eFirst paragraph\u003c/p\u003e\n        \u003cp\u003eSecond paragraph\u003c/p\u003e\n```\n````\n\n## 🛠️ How It Works\n\nThe tool processes markdown files and executes code blocks based on configuration settings. The core workflow is handled by several key components:\n\n1. 📋 **Configuration Loading** (`config_types.py`): Loads and validates the JSON configuration file\n2. 📝 **Markdown Processing** (`main.py`): Parses markdown files and processes code blocks\n3. ⚡ **Command Execution** (`execute.py`): Handles command execution and env vars\n4. 🎯 **Tag Processing** (`models.py`): Manages execution control tags\n\nControl how your documentation code blocks are executed with no code, just code block tags. 🏷️\n\n## ⚙️ JSON Configuration Options\n\n- 📂 `paths`: List of markdown files or directories to process (required)\n- 🔐 `env_vars`: Environment variables to set during execution\n- 🎬 `pre_cmds`: Commands to run before processing markdown\n- 🧹 `cleanup_cmds`: Commands to run after processing\n- 📂 `working_dir`: Working directory for command execution\n\n### 📝 Config Example\n\n````json\n{\n  \"paths\": [\"docs/README.md\"],\n  \"env_vars\": {\n    \"NODE_ENV\": \"test\"\n  },\n  \"working_dir\": \"docs/\",\n  \"debugging\": false,\n  \"pre_cmds\": [\"npm install\"],\n  \"cleanup_cmds\": [\"docker-compose down\"],\n}\n````\n\n## 🚧 Limitations\n\n- Not yet tested on Windows WSL, but should work.\n- Multi-line commands in docs are not supported yet\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freecepbcups%2Fdocci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freecepbcups%2Fdocci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freecepbcups%2Fdocci/lists"}