csdoc 0.1.0__tar.gz

csdoc-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+build/
+dist/
+*.egg-info/
+
+# Csound outputs
+*.wav
+*.aif
+*.ogg
+*.mp3
+
+# Project specific
+.DS_Store

csdoc-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: csdoc
+Version: 0.1.0
+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

csdoc-0.1.0/PUBLISHING.md

@@ -0,0 +1,41 @@
+# Publishing csdoc to PyPI
+
+## Prerequisites
+
+1.  **PyPI Account**: You must have an account on [PyPI](https://pypi.org/).
+2.  **API Token**: Create an API token on PyPI.
+    *   Go to **Account Settings** -> **API Tokens**.
+    *   Create a new token (scope it to "Entire account" if `csdoc` doesn't exist yet, or just for `csdoc` if it does).
+    *   **Copy the token** (it starts with `pypi-`).
+
+## Publishing with `uv` (Recommended)
+
+Since this project uses `uv`, you can publish directly with it.
+
+1.  **Build the package**:
+    ```bash
+    uv build
+    ```
+    This creates `dist/csdoc-0.1.0.tar.gz` and `dist/csdoc-0.1.0-py3-none-any.whl`.
+
+2.  **Publish**:
+    ```bash
+    uv publish --token <your-pypi-token>
+    ```
+    *   Replace `<your-pypi-token>` with your actual token.
+    *   Alternatively, set the `UV_PUBLISH_TOKEN` environment variable.
+
+## Publishing with `twine` (Alternative)
+
+If you prefer standard tools:
+
+1.  Install twine:
+    ```bash
+    uv pip install twine  # or pip install twine
+    ```
+
+2.  Upload:
+    ```bash
+    twine upload dist/*
+    ```
+    You will be prompted for your username (`__token__`) and password (the API token).

csdoc-0.1.0/README.md

@@ -0,0 +1,89 @@
+# 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