Metadata-Version: 2.4
Name: csdoc
Version: 0.1.4
Summary: Documentation generator for Csound projects
Project-URL: Homepage, https://github.com/kunstmusik/csdoc
Project-URL: Repository, https://github.com/kunstmusik/csdoc
Project-URL: Bug Tracker, https://github.com/kunstmusik/csdoc/issues
Author-email: Steven Yi <stevenyi@gmail.com>
License-Expression: MIT
Keywords: audio,csound,documentation,music
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: jinja2>=3.1.6
Requires-Dist: markdown>=3.10.1
Requires-Dist: typer>=0.21.1
Description-Content-Type: text/markdown

# 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`:

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

Or install it in your environment:

```bash
pip install csdoc
```

## Usage

### Build Documentation

```bash
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

```bash
csdoc json <source_file>
```

## Documentation Format

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

### Example

```csound
/**
 * 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.

```bash
# Install dependencies
uv sync

# Run the CLI
uv run csdoc --help
```

## License

MIT
