Doc Command

The doc command introspects a Rumour workflow directory and generates a Markdown documentation file that describes every request node, its HTTP method and URL, the variables it produces (extracts), and the variables it consumes (references). It also renders a Mermaid dependency graph showing how nodes are connected through variable flows.

This makes it easy to onboard new teammates, document your API test suite, or track how a workflow has changed over time.

Basic Usage

rumour doc <PATH> [OPTIONS]

• <PATH> — Path to the workflow directory containing .toml request files.

Options

Option	Short	Default	Description
--output	-o	README.md	Output file path for the generated documentation
--yes	-y	false	Auto-confirm overwrite if the output file already exists

How It Works

When you run rumour doc, the engine:

1. Walks the directory recursively — finds all .toml files, skipping .env.toml, .config.toml, collection.toml, and internal or build directories (.rumour/, target/, node_modules/).
2. Parses each request file — reads the HTTP method, URL, [extract] section (variables produced), and header/body references (variables consumed).
3. Builds the workflow dependency graph — same graph used by rumour run to determine execution order and variable flow.
4. Generates a Markdown document with two sections:
   • Topology — a Mermaid graph TD diagram showing data flow edges between nodes.
   • Node Inventory — a detailed list of every request with its method, URL, produced variables, and consumed variables.
5. Writes the output file — defaults to README.md in the current directory.

Example 1 — Generate Documentation (Default Output)

rumour doc ./run_example/

Since no --output is provided, the file is written to README.md in the current working directory. If README.md already exists, Rumour prompts for confirmation:

Generating documentation for ./run_example/...
File README.md already exists. Overwrite? [y/N]

Typing N or pressing Enter (default is No) aborts:

Aborted.

Example 2 — Custom Output File

rumour doc ./run_example/ --output ./run_example/WORKFLOW.md

Output:

Generating documentation for ./run_example/...
PASS Documentation generated at ./run_example/WORKFLOW.md

What this means:

• The file is written to the path you specified — the directory must already exist.
• The PASS prefix confirms the write succeeded.

Example 3 — Auto-Confirm Overwrite (-y)

Use -y to overwrite an existing file without being prompted — useful in CI/CD pipelines and scripts:

rumour doc ./requests/ --output README.md -y

Output:

Generating documentation for ./requests/...
PASS Documentation generated at README.md

Example 4 — A Real Workflow

Given a workflow directory with these request files:

run_example/
├── 01_get.toml        # GET {{base_url}}/get
├── 02_post.toml       # POST {{base_url}}/post — extracts: token, post.id
├── 03_dependent.toml  # GET {{base_url}}/bearer
├── 04_fail.toml       # GET {{base_url}}/status/404
└── 05_data.toml       # GET {{base_url}}/anything?user={{user_id}}

rumour doc ./run_example/ --output ./run_example/WORKFLOW.md -y

Output:

Generating documentation for ./run_example/...
PASS Documentation generated at ./run_example/WORKFLOW.md

Generated WORKFLOW.md:

# Rumour Workflow: run_example

## 🗺 Topology

```mermaid
graph TD
```

## Node Inventory

### 02_post
- **Method**: `POST`
- **URL**: `{{base_url}}/post`
- **Produces**:
  - `token`
  - `post.id`
- **Consumes**:
  - `base_url`

### 01_get
- **Method**: `GET`
- **URL**: `{{base_url}}/get`
- **Consumes**:
  - `base_url`

### 03_dependent
- **Method**: `GET`
- **URL**: `{{base_url}}/bearer`
- **Consumes**:
  - `base_url`

### 04_fail
- **Method**: `GET`
- **URL**: `{{base_url}}/status/404`
- **Consumes**:
  - `base_url`

### 05_data
- **Method**: `GET`
- **URL**: `{{base_url}}/anything?user={{user_id}}`
- **Consumes**:
  - `user_id`
  - `base_url`

What this output means:

• # Rumour Workflow: run_example — the title is derived from the input directory's name.
• ## 🗺 Topology — the Mermaid graph diagram. When nodes have explicit [dependencies] declared, directed arrows appear here showing which node feeds variables to which. In this example there are no explicit cross-file dependencies declared, so the graph body is empty.
• ## Node Inventory — one sub-section per request node:
  • Method — the HTTP verb from [request].method.
  • URL — the raw URL template from [request].url (variables are not resolved — they appear as {{name}}).
  • Produces — variables this node extracts via [extract], available for downstream nodes.
  • Consumes — variables this node references in its URL, headers, or body.

Topology Graph — When Are Arrows Shown?

The 🗺 Topology Mermaid diagram shows directed data-flow arrows when the workflow graph has explicit edges — i.e., when nodes declare [dependencies] or when the graph inference engine detects a producer-consumer relationship.

For example, if 02_post.toml produces token and 03_dependent.toml declares a dependency on it:

• Solid arrows (-->) represent execution order edges (one node must run before another).
• Dashed arrows (-.->) represent variable flow edges (one node produces a variable that another consumes).

What Is Included vs. Skipped

Included

Content	Condition
Any .toml file	Valid [request] section present
Nested sub-directories	Recursively traversed

Skipped

Content	Reason
*.env.toml	Environment configuration, not a request
*.config.toml	Configuration file
collection.toml, _collection.toml	Collection metadata
.rumour/ directory	Internal Rumour state directory
target/ directory	Compiled build output
node_modules/ directory	Node.js dependencies

Common Use Cases

Document a Workflow for Your Team

rumour doc ./api_tests/ --output ./api_tests/README.md -y

Commit README.md to your repository so teammates can understand the workflow at a glance without reading every .toml file.

Regenerate Docs in CI/CD

Add to your CI pipeline to keep docs always up to date with the workflow:

rumour doc ./tests/ --output ./docs/workflow.md -y
git add docs/workflow.md
git commit -m "docs: regenerate workflow docs"

Generate to a Specific Location

# Generate into a docs subfolder
rumour doc ./requests/ --output ./docs/api-workflow.md -y