pixotope-documentalist

Parses JSDoc-style API documentation comments from source files (TypeScript, JavaScript, Python, Rust) and publishes them as formatted pages to Confluence.

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) {
    // ...
}

Tag Reference

| Tag | Required | Description | |-----|----------|-------------| | @api | Yes | Endpoint name (displayed as title) | | @group | No | Section grouping header | | @kind | No | call (default), get, set, state (supports both Get and Set) | | @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 |

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"
    confluence_id:
      master: "1234567890"
      release: "0987654321"
    sources:
      - path: "packages/Daemon/src/endpoints/calls.ts"   # single file

  - id: daemon_all
    title: "Daemon API - All"
    confluence_id:
      master: "3333333333"
      release: "4444444444"
    sources:
      - path: "packages/Daemon/src/endpoints/"           # entire folder (recursive)

• 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
• 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.

CLI Commands

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

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

# Parse + render + upload to Confluence
npx pixotope-documentalist publish --config ./config.yml --target master

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

Options

| 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

• .ts, .tsx (TypeScript)
• .js, .jsx (JavaScript)
• .py (Python)
• .rs (Rust)
• .h, .cpp, .hpp (C++)