csdoc

csdoc is a documentation generator for Csound projects. It parses Csound code (.csd, .orc, .inc, etc.) and extracts JSDoc-style comment blocks to generate a beautiful, static HTML documentation site.

Features

• Standard Syntax: Supports opcode (UDOs), instr, and struct definitions.
• Recursive Parsing: Automatically follows #include statements.
• Rich Comments: Supports @param, @return, and Markdown in descriptions.
• Modern CLI: Easy to use with uv or as a standalone tool.

Installation

You can run csdoc directly using uvx:

uvx --from git+https://github.com/yourusername/csdoc csdoc build main.csd

Or install it in your environment:

pip install csdoc

Usage

Build Documentation

csdoc build <source_file> [options]

• <source_file>: The entry point of your Csound project (e.g., main.csd).
• -o, --output <dir>: The directory to save the generated site (default: dist).

Export JSON

csdoc json <source_file>

Documentation Format

csdoc looks for tags within /** ... */ comment blocks immediately preceding a definition.

Example

/**
 * A gain control UDO.
 * 
 * This opcode applies a simple linear gain to an audio signal.
 * 
 * @param ain   The input audio signal
 * @param kgain The gain multiplier (0.0 to 1.0)
 * @return aout  The processed audio signal
 */
opcode Gain, a, ak
  ain, kgain xin
  xout ain * kgain
endop

Supported Tags

Tag	Description
@param {type} name Description	Documents a parameter or p-field. Type is optional.
@return {type} Description	Documents a return value. Type is optional.
@returns	Alias for @return.

Descriptions support standard Markdown syntax, including code blocks, bold text, and lists.

Development

This project uses uv for dependency management.

# Install dependencies
uv sync

# Run the CLI
uv run csdoc --help

License

MIT