primary goal

Rundoc Tutorial: Executing Code Directly from Markdown Files

Keeping documentation synchronized with code is a major challenge in software development. Code snippets in README files often become outdated as APIs change. rundoc solves this problem by allowing you to execute code blocks directly from Markdown files, turning your documentation into automated scripts. What is Rundoc?

rundoc is a command-line tool that parses Markdown files, extracts code blocks, and runs them sequentially in an interactive or automated session. It supports multiple programming languages and interpreters, making it ideal for tutorials, deployment guides, and integration tests. Core Scenarios

Depending on your workflow, you will likely use rundoc in one of two ways:

Scenario 1: Interactive Documentation (User-Facing Tutorials)

In this setup, you use rundoc to guide a user through a tutorial step-by-step. The user reviews each code block before pressing a key to execute it.

Best For: Onboarding guides, complex environment setups, and educational tutorials.

Key Advantage: Prevents users from making copy-paste errors while keeping them engaged. Scenario 2: Automated Testing (CI/CD Pipelines)

In this setup, rundoc runs completely unattended. It executes every code block in the Markdown file from top to bottom and fails if any command returns a non-zero exit code.

Best For: Verifying that README examples still work, automated deployment scripts, and regression testing for documentation.

Key Advantage: Catch broken documentation automatically before it reaches your users. Step-by-Step Implementation 1. Installation

Install rundoc via pip. It is recommended to use a virtual environment. pip install rundoc Use code with caution. 2. Formatting the Markdown File

rundoc identifies executable code blocks using standard Markdown fence tags. You must specify the language/interpreter. You can also name blocks using tags to control execution flow. Create a file named tutorial.md:

# Sample Tutorial This block will execute in the bash shell. bash echo "Initializing setup..." export APP_ENV="production" Next, we run a Python script that utilizes the environment variable set above. python import os print(f"The application environment is: {os.getenv('APP_ENV')}") Use code with caution. 3. Executing the File To run interactively (Scenario 1):

Run the command below. rundoc will pause at each block, show you the code, and wait for confirmation. rundoc run tutorial.md Use code with caution. To run automatically (Scenario 2):

Add the –auto flag to execute the entire file without human intervention. rundoc run –auto tutorial.md Use code with caution. Advanced Capabilities

Variable Prompts: You can define placeholders in your Markdown (e.g., # arg: db_password). rundoc will prompt the user to input these values at runtime.

Session Continuity: Environment variables and state persist across code blocks of the same interpreter type during a single run.

Block Filtering: Use tags to execute only specific sections of a large Markdown document using the –tags option.

To help tailor more advanced tips for your workflow, could you share a bit more context?

Which programming languages or tools do you plan to execute most often?