pixotope-documentalist

Parses JSDoc-style API documentation comments and TypeScript interface definitions from source files (TypeScript, JavaScript, Python, Rust, C++) and publishes them as formatted pages to Confluence. Markdown files can also be included as freeform content blocks alongside your API docs.

Installation

npm install pixotope-documentalist

Or run directly with npx:

npx pixotope-documentalist publish --config ./config.yml

Quick Start

1. Add doc comments to your source files
2. Create a config.yml pointing to your sources and Confluence pages
3. Set environment variables for Confluence auth
4. Run npx pixotope-documentalist publish

Comment Format

TypeScript / JavaScript

Use JSDoc-style block comments with @api as the entry tag:

/**
 * @api CopyShowFileToLocal
 * @group Shows
 * @kind call
 * @description Copies a show file from the server to this machine.
 * @param {string} ShowName - Name of the show to copy.
 * @param {boolean} [Overwrite=false] - Whether to overwrite existing file.
 * @returns {boolean} Success - Whether the copy succeeded.
 * @example Copy a show
 * >>> {"Type":"Call","Target":"Machine1-Daemon","Method":"CopyShowFileToLocal"}
 * >>> {"Params":{"ShowName":"Show1"}}
 * <<< {"Type":"CallResult","Method":"CopyShowFileToLocal"}
 * <<< {"Result":{"Success":true}}
 * @warning This may take a while for large files.
 * @since 23.3.0
 */
export const copyShowFileToDisk = async (...) => { ... };

Python

Use # comment blocks:

# @api DiscoverDevices
# @group Network
# @kind call
# @description Discovers available devices on the local network.
# @param {string} Subnet - The subnet to scan.
# @param {integer} Timeout - Scan timeout in milliseconds.
# @returns {boolean} Success - Whether the scan completed.
def discover_devices(subnet: str, timeout: int) -> dict:
    pass

Rust

Use /// triple-slash doc comments (consecutive lines form one block):

/// @api DiscoverDevices
/// @group Network
/// @kind call
/// @description Discovers available devices on the local network.
/// @param {string} Subnet - The subnet to scan.
/// @param {integer} Timeout - Scan timeout in milliseconds.
/// @returns {boolean} Success - Whether the scan completed.
pub fn discover_devices(subnet: &str, timeout: u64) {
    // ...
}

Markdown files

Any .md file listed as a source is read in full and rendered directly as content on the Confluence page — no comment tags needed. This is useful for introductions, changelogs, troubleshooting guides, or any prose that belongs alongside your API docs.

sources:
  - path: "docs/intro.md"        # rendered as HTML content block
  - path: "src/calls/"           # parsed for @api tags as usual
  - path: "docs/notes.md"        # another content block, appears after the API groups

Standard Markdown is supported: headings, bold, italic, code, fenced code blocks, bullet and numbered lists, blockquotes, tables, and links.

TypeScript interfaces

Use @kind interface in a JSDoc block above an interface declaration. The property tree is extracted automatically — no @param or @value tags needed.

interface Color {
  R: number;
  G: number;
  B: number;
  A: number;
}

/**
 * @group State
 * @description The persisted state tree.
 */

/**
 * @kind interface
 * @description The full state of the system.
 */
interface State {
  State: {
    FrameRate: number;
    Cameras: Record<string, Camera>;
    Projects: string[];
    WorkingColorSpace: "sRGB" | "Rec2020" | "ACESAP1";
  };
}

Only @kind interface-annotated interfaces become roots. Others (like Color) are helpers resolved when referenced.

Tag Reference

Comment mode tags (for @api endpoints)

| Tag | Required | Description | |-----|----------|-------------| | @api | Yes | Endpoint name (displayed as title) | | @group | No | Section grouping header (with optional @description) | | @kind | No | call (default), get, set, state, or interface | | @description | No | Multi-line description (continues until next tag) | | @param | No | {type} Name - Description. [Name] = optional, [Name=default] = with default | | @returns | No | {type} Name - Description | | @example | No | Title on first line, >>> for request messages, <<< for response messages | | @warning | No | Warning/note text | | @since | No | Version when this was introduced | | @deprecated | No | Deprecation notice | | @internal | No | Flag to exclude from published docs | | @value | No | For state docs: {type} Name - Description |

Interface mode tags (for TypeScript interface trees)

When @kind interface appears in a file, it switches to interface parsing mode using the TypeScript compiler API. Properties, nested types, Records, arrays, and unions are resolved automatically.

| Tag | Description | |-----|-------------| | @kind interface | Marks an interface declaration as a root value tree | | @group | Assigns the interface to a named group (standalone block with optional @description) | | @description | Description for the interface or for the group (depending on which block it appears in) |

Configuration

Create a config.yml in your project:

confluence:
  base_url: "https://your-domain.atlassian.net/wiki/rest/api/content"

source_root: "."

documents:
  - id: daemon_calls
    title: "Daemon API - Calls"
    description: "Covers all call-type RPC endpoints."   # optional — plain string or path to a .md file
    confluence_id:
      master: "1234567890"
      release: "0987654321"
    sources:
      - path: "packages/Daemon/src/endpoints/calls.ts"   # single file

  - id: store_state
    title: "Store API - State"
    description: "docs/store_overview.md"
    confluence_id:
      master: "3333333333"
      release: "4444444444"
    sources:
      - path: "packages/Store/src/interfaces.ts"         # interface mode (auto-detected)
      - path: "packages/Store/src/gets.ts"               # comment mode (auto-detected)
      - path: "packages/Store/src/endpoints/"             # entire folder (recursive)
        mode: comments                                    # explicit mode override

• source_root: base path for resolving relative source paths (relative to config file location)
• confluence_id.master: page ID for master/development docs
• confluence_id.release: page ID for release docs
• description (optional): text rendered at the top of the Confluence page body, beneath the page title. Accepts either a plain string or a path to a .md file (resolved relative to the config file). Markdown is rendered to HTML.
• sources[].path: can point to a single file or a folder. When a folder is given, all supported files inside are scanned recursively. node_modules and hidden directories are skipped. Supported extensions: .ts, .tsx, .js, .jsx, .py, .rs, .h, .cpp, .hpp, .md.
• sources[].mode (optional): "comments", "interfaces", or "markdown". When omitted, auto-detected: .md files are always markdown mode; files containing @kind interface use interface mode; everything else defaults to comments mode. Source order matters — groups appear in the output in the order their source files are listed.

CLI Commands

# Parse source files and output JSON (for debugging)
npx pixotope-documentalist parse -c ./config.yml --verbose

# Parse + render to HTML files locally (no API calls)
npx pixotope-documentalist preview -c ./config.yml

# Parse + render + upload to Confluence (skips if content unchanged)
npx pixotope-documentalist publish -c ./config.yml -t master

# Parse + render + force-upload to Confluence (always writes, skips diff check)
npx pixotope-documentalist update -c ./config.yml -t release

# Show what would change without publishing
npx pixotope-documentalist diff -c ./config.yml -t master

Commands

| Command | Description | |---------|-------------| | parse | Parse sources → JSON (debug output in output/collected/) | | preview | Parse + render → HTML files (in output/formatted/) | | publish | Parse + render + upload to Confluence. Skips if content is unchanged. | | update | Parse + render + force-upload to Confluence. Always writes, no diff check. | | diff | Show what would change without publishing |

Options

All options support both short (-c) and long (--config) forms.

| Option | Description | Default | |--------|-------------|---------| | -c, --config <path> | Path to config.yml | config.yml | | -d, --document <id> | Process only this document | all documents | | -t, --target <env> | master or release | master | | --version-stamp <ver> | Version stamp | local | | -v, --verbose | Verbose logging | off |

Environment Variables

| Variable | Purpose | |----------|---------| | CONFLUENCE_USER | Confluence account email | | CONFLUENCE_TOKEN | Confluence API token (generate here) |

Create a .env file (git-ignored) for local use:

[email protected]
CONFLUENCE_TOKEN=your_api_token

Supported File Types

| Extension | Mode | How it's processed | |-----------|------|--------------------| | .ts, .tsx | comments or interfaces | JSDoc /** ... */ blocks, or TypeScript interface AST | | .js, .jsx | comments | JSDoc /** ... */ blocks | | .py | comments | Consecutive # lines | | .rs | comments | Consecutive /// lines | | .h, .cpp, .hpp | comments | JSDoc /** ... */ blocks | | .md | markdown | Whole file rendered as HTML content block |