csdoc 0.1.0__py3-none-any.whl

csdoc/cli.py

@@ -0,0 +1,60 @@
+import typer
+from typing import Optional
+from pathlib import Path
+from .parser.csound import CsoundParser
+from .generator.builder import SiteBuilder
+
+app = typer.Typer()
+
+@app.command()
+def build(
+    source: Path = typer.Argument(..., exists=True, help="The Csound source file (e.g. main.csd or .orc)"),
+    output: Path = typer.Option(Path("dist"), "--output", "-o", help="Output directory for the documentation site")
+):
+    """
+    Build documentation for a Csound project.
+    """
+    typer.echo(f"Parsing project from {source}...")
+    
+    parser = CsoundParser()
+    try:
+        entries = parser.parse_project(str(source))
+    except Exception as e:
+        typer.echo(f"Error parsing project: {e}", err=True)
+        raise typer.Exit(code=1)
+        
+    typer.echo(f"Found {len(entries)} documented entries.")
+    
+    typer.echo(f"Building site in {output}...")
+    # Use the parent directory of the source as the base path for relativization
+    base_path = str(source.resolve().parent)
+    builder = SiteBuilder(str(output), base_path=base_path)
+    builder.build(entries)
+    
+    typer.echo("Done!")
+
+@app.command()
+def json(
+    source: Path = typer.Argument(..., exists=True, help="The Csound source file"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output JSON file")
+):
+    """
+    Export parsed documentation as JSON.
+    """
+    import json
+    import dataclasses
+    
+    parser = CsoundParser()
+    entries = parser.parse_project(str(source))
+    
+    data = [dataclasses.asdict(e) for e in entries]
+    
+    if output:
+        with open(output, 'w') as f:
+            json.dump(data, f, indent=2)
+        typer.echo(f"JSON written to {output}")
+    else:
+        typer.echo(json.dumps(data, indent=2))
+
+if __name__ == "__main__":
+    app()

csdoc/generator/builder.py

@@ -0,0 +1,63 @@
+import os
+import shutil
+from typing import List, Optional, Dict, Tuple
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+import markdown
+from ..models import DocEntry
+
+class SiteBuilder:
+    def __init__(self, output_dir: str, base_path: Optional[str] = None):
+        self.output_dir = output_dir
+        self.base_path = base_path or os.getcwd()
+        self.template_dir = os.path.join(os.path.dirname(__file__), 'templates')
+        self.env = Environment(
+            loader=FileSystemLoader(self.template_dir),
+            autoescape=select_autoescape(['html', 'xml'])
+        )
+        # Register markdown filter
+        self.env.filters['markdown'] = lambda text: markdown.markdown(text) if text else ""
+
+    def build(self, entries: List[DocEntry]):
+        """
+        Builds the documentation site.
+        """
+        if not os.path.exists(self.output_dir):
+            os.makedirs(self.output_dir)
+            
+        # Relativize paths for display
+        for entry in entries:
+            if os.path.isabs(entry.file_path):
+                entry.file_path = os.path.relpath(entry.file_path, self.base_path)
+
+        # Group entries by name and type (for overloads)
+        # We group by (name, type) so that an instrument and UDO with same name are separate
+        grouped: Dict[Tuple[str, str], List[DocEntry]] = {}
+        for entry in entries:
+            key = (entry.name, type(entry).__name__)
+            if key not in grouped:
+                grouped[key] = []
+            grouped[key].append(entry)
+
+        # Convert to a list for Jinja2
+        entry_groups = []
+        for (name, entry_type), items in grouped.items():
+            entry_groups.append({
+                "name": name,
+                "type": entry_type.replace('Entry', ''),
+                "entries": items
+            })
+
+        template = self.env.get_template('index.html')
+        
+        # Collect all entry names for type linking
+        documented_names = {entry.name for entry in entries}
+        
+        output_content = template.render(
+            entry_groups=entry_groups,
+            documented_names=documented_names
+        )
+        
+        with open(os.path.join(self.output_dir, 'index.html'), 'w', encoding='utf-8') as f:
+            f.write(output_content)
+        
+        print(f"Documentation generated in {self.output_dir}")

csdoc/generator/templates/base.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}csdoc{% endblock %}</title>
+    <style>
+        :root {
+            --primary-color: #007bff;
+            --bg-color: #ffffff;
+            --text-color: #333333;
+            --sidebar-bg: #f8f9fa;
+            --border-color: #dee2e6;
+        }
+        body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; color: var(--text-color); display: flex; height: 100vh; }
+        
+        nav { width: 280px; background: var(--sidebar-bg); border-right: 1px solid var(--border-color); overflow-y: auto; padding: 20px; flex-shrink: 0; }
+        nav h3 { margin-top: 0; font-size: 1.2rem; }
+        nav ul { list-style: none; padding: 0; }
+        nav li { margin-bottom: 8px; }
+        nav a { text-decoration: none; color: var(--text-color); display: block; padding: 4px 8px; border-radius: 4px; }
+        nav a:hover { background: rgba(0,0,0,0.05); color: var(--primary-color); }
+        
+        main { flex: 1; padding: 40px; overflow-y: auto; }
+        
+        h1, h2, h3, h4, h5, h6 { margin-top: 0; color: #222; }
+        h1 { border-bottom: 2px solid var(--border-color); padding-bottom: 10px; margin-bottom: 30px; }
+        
+        .doc-entry { margin-bottom: 50px; padding-bottom: 30px; border-bottom: 1px solid var(--border-color); }
+        .doc-entry:last-child { border-bottom: none; }
+        
+        .signature { font-family: monospace; background: #f1f3f5; padding: 10px; border-radius: 4px; margin: 10px 0 20px 0; overflow-x: auto; }
+        
+        .tag-list { list-style: none; padding: 0; }
+        .tag-list li { margin-bottom: 8px; }
+        .tag-name { font-weight: 600; color: #495057; display: inline-block; min-width: 100px; }
+        .tag-type { font-family: monospace; color: #e83e8c; background: rgba(232, 62, 140, 0.1); padding: 2px 4px; border-radius: 3px; font-size: 0.9em; margin-right: 5px; }
+        
+        code { font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; background: rgba(0,0,0,0.04); padding: 2px 4px; border-radius: 3px; }
+        pre { background: #2d2d2d; color: #f8f8f2; padding: 15px; border-radius: 5px; overflow-x: auto; }
+        pre code { background: none; color: inherit; padding: 0; }
+
+        /* Badges */
+        .badge {
+            display: inline-block;
+            padding: 2px 6px;
+            font-size: 0.75em;
+            font-weight: 600;
+            line-height: 1;
+            text-align: center;
+            white-space: nowrap;
+            vertical-align: baseline;
+            border-radius: 4px;
+            text-transform: uppercase;
+            margin-left: 5px;
+        }
+        .badge-udo { background-color: #fff3cd; color: #856404; border: 1px solid #ffeeba; }
+        .badge-instrument { background-color: #d4edda; color: #155724; border: 1px solid #c3e6cb; }
+        .badge-struct { background-color: #ffe5d0; color: #854d0e; border: 1px solid #fbd6b1; }
+    </style>
+</head>
+<body>
+    <nav>
+        <h3>Contents</h3>
+        <ul>
+        {% for group in entry_groups %}
+            <li>
+                <a href="#{{ group.name }}" style="display: flex; justify-content: space-between; align-items: center;">
+                    <span>{{ group.name }}</span>
+                    <span class="badge badge-{% if group.type == 'UDO' %}udo{% elif group.type == 'Instrument' %}instrument{% else %}struct{% endif %}">
+                        {{ group.type }}
+                    </span>
+                </a>
+            </li>
+        {% endfor %}
+        </ul>
+    </nav>
+    <main>
+        {% block content %}{% endblock %}
+    </main>
+</body>
+</html>

csdoc/generator/templates/index.html

@@ -0,0 +1,87 @@
+{% extends "base.html" %}
+
+{% block content %}
+    <h1>Project Documentation</h1>
+    
+    {% for group in entry_groups %}
+        <div class="doc-entry" id="{{ group.name }}">
+            <h2>
+                {{ group.name }} 
+                <span class="badge badge-{% if group.type == 'UDO' %}udo{% elif group.type == 'Instrument' %}instrument{% else %}struct{% endif %}">
+                    {{ group.type }}
+                </span>
+            </h2>
+
+            {# Handle multiple signatures for overloads #}
+            {% for entry in group.entries %}
+                <div class="overload-item">
+                    <div class="signature">
+                        {% if group.type == 'UDO' %}
+                            {# Functional Form Only #}
+                            <div>
+                                {% if entry.returns %}
+                                    {% for ret in entry.returns %}{{ ret.name or '?' }}{% if not loop.last %}, {% endif %}{% endfor %} = 
+                                {% elif entry.outputs %}
+                                    {{ entry.outputs }} = 
+                                {% endif %}
+                                <strong>{{ entry.name }}</strong>({% for param in entry.params %}{{ param.name or '?' }}{% if not loop.last %}, {% endif %}{% endfor %})
+                            </div>
+                        {% else %}
+                            {# Instrument / Struct form (simple) #}
+                            {% if entry.outputs %}{{ entry.outputs }} {% endif %}
+                            <strong>{{ entry.name }}</strong>
+                            {% if entry.inputs %} {{ entry.inputs }}{% endif %}
+                        {% endif %}
+                    </div>
+                    
+                    <div class="description">
+                        {{ entry.description | markdown | safe }}
+                    </div>
+                    
+                    {% if entry.params %}
+                    <h3>Parameters</h3>
+                    <ul class="tag-list">
+                        {% for param in entry.params %}
+                        <li>
+                            <span class="tag-name">{{ param.name }}</span>
+                            {% if param.type_info %}
+                                {% if param.type_info in documented_names %}
+                                    <a href="#{{ param.type_info }}" class="tag-type">{{ param.type_info }}</a>
+                                {% else %}
+                                    <span class="tag-type">{{ param.type_info }}</span>
+                                {% endif %}
+                            {% endif %}
+                            <span class="tag-desc">{{ param.description }}</span>
+                        </li>
+                        {% endfor %}
+                    </ul>
+                    {% endif %}
+
+                    {% if entry.returns %}
+                    <h3>Returns</h3>
+                    <ul class="tag-list">
+                        {% for ret in entry.returns %}
+                        <li>
+                            <span class="tag-name">{% if ret.name %}{{ ret.name }}{% else %}return{% endif %}</span>
+                            {% if ret.type_info %}
+                                {% if ret.type_info in documented_names %}
+                                    <a href="#{{ ret.type_info }}" class="tag-type">{{ ret.type_info }}</a>
+                                {% else %}
+                                    <span class="tag-type">{{ ret.type_info }}</span>
+                                {% endif %}
+                            {% endif %}
+                            <span class="tag-desc">{{ ret.description }}</span>
+                        </li>
+                        {% endfor %}
+                    </ul>
+                    {% endif %}
+                    
+                    <p style="font-size: 0.8em; color: #999; margin-top: 10px;">
+                        Defined in <code>{{ entry.file_path }}</code> at line {{ entry.line_number }}
+                    </p>
+                    {% if not loop.last %}<hr style="border: 0; border-top: 1px dashed #eee; margin: 20px 0;">{% endif %}
+                </div>
+            {% endfor %}
+        </div>
+    {% endfor %}
+{% endblock %}

csdoc/models.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+@dataclass
+class DocParam:
+    """Represents a @param tag"""
+    name: str = ""
+    description: str = ""
+    type_info: str = "" # e.g. from {type} if supported, or inferred
+
+@dataclass
+class DocReturn:
+    """Represents a @return tag"""
+    name: str = ""
+    type_info: str = ""
+    description: str = ""
+
+@dataclass
+class DocEntry:
+    """Base class for all documented entities"""
+    name: str = ""
+    description: str = "" # Main description from the docblock
+    line_number: int = 0
+    file_path: str = ""
+    params: List[DocParam] = field(default_factory=list)
+    returns: List[DocReturn] = field(default_factory=list)
+    raw_docblock: str = "" # The original comment block
+
+@dataclass
+class UDOEntry(DocEntry):
+    """Represents a User Defined Opcode"""
+    inputs: str = ""  # The input string, e.g. "a, k"
+    outputs: str = "" # The output string, e.g. "a"
+    arg_names: List[str] = field(default_factory=list) # Extracted argument names
+    deprecated: bool = False
+
+@dataclass
+class InstrumentEntry(DocEntry):
+    """Represents a Csound Instrument"""
+    id: str = "" # Can be number or name
+    # Instruments might have p-fields described in params
+
+@dataclass
+class StructEntry(DocEntry):
+    """Represents a typedef/struct"""
+    members: List[str] = field(default_factory=list) 

csdoc/parser/csound.py

@@ -0,0 +1,205 @@
+import re
+import os
+from typing import List, Set, Optional
+from .docblock import parse_docblock
+from ..models import DocEntry, UDOEntry, InstrumentEntry, StructEntry, DocParam, DocReturn
+
+class CsoundParser:
+    def __init__(self):
+        self.entries: List[DocEntry] = []
+        self.visited_files: Set[str] = set()
+
+    def parse_project(self, root_file: str) -> List[DocEntry]:
+        """
+        Parses a Csound project starting from a root file (e.g. .csd or .orc).
+        """
+        self.entries = []
+        self.visited_files = set()
+        
+        abs_path = os.path.abspath(root_file)
+        if not os.path.exists(abs_path):
+            raise FileNotFoundError(f"File not found: {root_file}")
+            
+        self._parse_file(abs_path)
+        return self.entries
+
+    def _parse_file(self, file_path: str):
+        if file_path in self.visited_files:
+            return
+        self.visited_files.add(file_path)
+        
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+        except Exception as e:
+            print(f"Warning: Could not read {file_path}: {e}")
+            return
+
+        # 1. Handle Includes
+        # Regex for #include "..." or #include <...>
+        # Csound usually uses #include "file"
+        include_iter = re.finditer(r'^\s*#include\s+"([^"]+)"', content, re.MULTILINE)
+        for match in include_iter:
+            inc_path = match.group(1)
+            # Resolve path relative to current file
+            current_dir = os.path.dirname(file_path)
+            full_inc_path = os.path.join(current_dir, inc_path)
+            self._parse_file(os.path.abspath(full_inc_path))
+
+        # 2. Parse DocBlocks and Entries
+        # We assume docblocks are /** ... */
+        # We iterate through the file looking for docblocks.
+        # When we find one, we look ahead for the definition.
+        
+        # Regex for docblock
+        docblock_pattern = re.compile(r'/\*\*(.*?)\*/', re.DOTALL)
+        
+        last_pos = 0
+        matches = list(docblock_pattern.finditer(content))
+        
+        for m in matches:
+            block_content = m.group(1)
+            end_pos = m.end()
+            
+            # Find the line number of the start of the block
+            # (Crude approximation or accurate calculation)
+            preceeding_text = content[:m.start()]
+            line_number = preceeding_text.count('\n') + 1
+            
+            # Look ahead for the next definition
+            # We look from end_pos until we find a definition or another docblock or end of file
+            # Actually, just look for the *next* definition pattern.
+            # If there is a huge gap or another docblock, maybe it's a detached comment?
+            # But standard behavior: take the *first* matching declaration after the comment.
+            # We should probably limit the search distance or stop at next comment.
+            
+            # Let's get the text chunk after the comment
+            chunk_start = end_pos
+            # Use a limited chunk to avoid scanning whole file? Or just regex search from pos
+            
+            # Regexes for definitions
+            # 1. Old-style: opcode name, out, in
+            opcode_old_re = re.compile(r'\bopcode\b\s+([\w\d_]+)\s*,\s*(\S+)\s*,\s*(\S+)')
+            # 2. New-style (Csound 7): opcode name(arg list):ret types
+            # Example: opcode MyOp(k1:k, i1:i):k
+            opcode_new_re = re.compile(r'\bopcode\b\s+([\w\d_]+)\s*\((.*?)\)\s*(?::\s*([ \t\w\d_,]+))?')
+            
+            # instr name
+            instr_re = re.compile(r'\binstr\b\s+([\w\d_]+)')
+            # struct name
+            struct_re = re.compile(r'\bstruct\b\s+(\w+)')
+            
+            # Search in the remaining content
+            search_text = content[chunk_start:]
+            next_docblock = docblock_pattern.search(search_text)
+            limit_pos = next_docblock.start() if next_docblock else len(search_text)
+            candidate_text = search_text[:limit_pos]
+            
+            # Find the earliest match
+            matches_found = []
+            m_opcode_old = opcode_old_re.search(candidate_text)
+            if m_opcode_old: matches_found.append((m_opcode_old.start(), 'opcode_old', m_opcode_old))
+            
+            m_opcode_new = opcode_new_re.search(candidate_text)
+            if m_opcode_new: matches_found.append((m_opcode_new.start(), 'opcode_new', m_opcode_new))
+
+            m_instr = instr_re.search(candidate_text)
+            if m_instr: matches_found.append((m_instr.start(), 'instr', m_instr))
+            
+            m_struct = struct_re.search(candidate_text)
+            if m_struct: matches_found.append((m_struct.start(), 'struct', m_struct))
+            
+            matches_found.sort(key=lambda x: x[0])
+            
+            if not matches_found:
+                continue
+                
+            match_type = matches_found[0][1]
+            match_obj = matches_found[0][2]
+            desc, params, returns = parse_docblock(block_content)
+            
+            entry = None
+            if match_type.startswith('opcode'):
+                if match_type == 'opcode_old':
+                    name = match_obj.group(1)
+                    outs = match_obj.group(2)
+                    ins = match_obj.group(3)
+                else: # opcode_new
+                    name = match_obj.group(1)
+                    arg_list = match_obj.group(2)
+                    ret_list = match_obj.group(3) or ""
+                    
+                    # Convert arg_list (e.g. "a1:a, k1:k") to types string (e.g. "ak")
+                    # Or if it's just "a1, k1", we can't really know unless we parse types.
+                    # Common Csound 7 style often omits types if they are default, but 
+                    # usually they are explicit in UDOs. 
+                    # If they are just names, maybe we just list names?
+                    # Let's try to extract types if present.
+                    in_types = []
+                    arg_names = []
+                    for arg in arg_list.split(','):
+                        arg = arg.strip()
+                        if not arg:
+                            continue
+                            
+                        # Extract name and type
+                        if ':' in arg:
+                            parts = arg.split(':')
+                            name = parts[0].strip()
+                            type_ = parts[-1].strip()
+                        else:
+                            name = arg
+                            # Heuristic: first character of name?
+                            type_ = arg[0] if arg else ""
+                            
+                        arg_names.append(name)
+                        in_types.append(type_)
+                    
+                    out_types = []
+                    for ret in ret_list.split(','):
+                        ret = ret.strip()
+                        if ret:
+                            out_types.append(ret)
+                    
+                    ins = "".join(in_types)
+                    outs = "".join(out_types)
+
+                entry = UDOEntry(
+                    name=name,
+                    description=desc,
+                    params=params,
+                    returns=returns,
+                    inputs=ins,
+                    outputs=outs,
+                    arg_names=arg_names if match_type != 'opcode_old' else [],
+                    line_number=line_number,
+                    file_path=file_path,
+                    raw_docblock=block_content
+                )
+            elif match_type == 'instr':
+                name = match_obj.group(1)
+                entry = InstrumentEntry(
+                    name=name, # name field in DocEntry
+                    id=name,
+                    description=desc,
+                    params=params,
+                    returns=returns,
+                    line_number=line_number,
+                    file_path=file_path,
+                    raw_docblock=block_content
+                )
+            elif match_type == 'struct':
+                name = match_obj.group(1)
+                entry = StructEntry(
+                    name=name,
+                    description=desc,
+                    params=params, # struct params? Members?
+                    returns=returns,
+                    line_number=line_number,
+                    file_path=file_path,
+                    raw_docblock=block_content
+                )
+                
+            if entry:
+                self.entries.append(entry)
+

csdoc/parser/docblock.py

@@ -0,0 +1,126 @@
+import re
+from typing import Dict, List, Tuple
+from ..models import DocParam, DocReturn
+
+def parse_docblock(content: str) -> Tuple[str, List[DocParam], List[DocReturn]]:
+    """
+    Parses the content of a docblock (inside /** ... */).
+    Returns (description, params, returns)
+    """
+    lines = content.splitlines()
+    cleaned_lines = []
+    
+    # Strip leading * from each line
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith('*'):
+            # Remove the first * and maybe one space
+            line = stripped[1:]
+            if line.startswith(' '):
+                line = line[1:]
+        else:
+            # Maybe it didn't start with *, just use stripped or original?
+            # Standard JSDoc often has * aligned. 
+            # If we stripped it, we lose indentation for code blocks.
+            # Let's try to be smart: remove optional whitespace then optional * then optional space.
+            # actually usually:
+            # /**
+            #  * desc
+            #  */
+            # so we just match ^\s*\*\s?
+            m = re.match(r'^\s*\*\s?(.*)', line)
+            if m:
+                line = m.group(1)
+            else:
+                line = line.strip()
+        cleaned_lines.append(line)
+        
+    full_text = '\n'.join(cleaned_lines).strip()
+    
+    # Now split by tags
+    # We look for @param, @return at start of lines (logically)
+    # But since we joined them, we can use regex or iterate lines again.
+    # Iterating lines is safer for context.
+    
+    description_lines = []
+    params = []
+    returns = []
+    
+    current_tag = None # None (desc), 'param', 'return'
+    current_buffer = [] 
+    
+    # Helper to flush current buffer
+    def flush():
+        nonlocal current_tag, current_buffer
+        text = '\n'.join(current_buffer).strip()
+        if not text:
+            return
+
+        if current_tag is None:
+            description_lines.append(text)
+        elif current_tag == 'param':
+            # Parse param: @param {type} name description
+            # or @param name description
+            # text starts after @param
+            # We need to handle the content we've collected
+            
+            # Regex for param:
+            # ^(\{.*?\})?\s*(\S+)\s*(.*)
+            # group 1: type (optional)
+            # group 2: name
+            # group 3: desc
+            m = re.match(r'^(?:\{([^\}]+)\})?\s*(\S+)\s*(.*)', text, re.DOTALL)
+            if m:
+                type_info = m.group(1) or ""
+                name = m.group(2)
+                desc = m.group(3)
+                params.append(DocParam(name=name, description=desc, type_info=type_info))
+            else:
+                # Fallback
+                params.append(DocParam(name="?", description=text))
+                
+        elif current_tag == 'return':
+            # @return {type} name description
+            # or @return name description
+            # Try to match {type} name desc first
+            m = re.match(r'^(?:\{([^\}]+)\})?\s*(\S+)\s*(.*)', text, re.DOTALL)
+            if m:
+                type_info = m.group(1) or ""
+                name = m.group(2)
+                desc = m.group(3)
+                returns.append(DocReturn(name=name, description=desc, type_info=type_info))
+            else:
+                returns.append(DocReturn(description=text))
+        
+        current_buffer = []
+
+    for line in cleaned_lines:
+        # Check for tag
+        m = re.match(r'^@(\w+)(?:\s+(.*))?$', line)
+        if m:
+            flush()
+            tag_name = m.group(1)
+            content_start = m.group(2) or ""
+            
+            if tag_name == 'param':
+                current_tag = 'param'
+                current_buffer = [content_start]
+            elif tag_name in ('return', 'returns'):
+                current_tag = 'return'
+                current_buffer = [content_start]
+            else:
+                # Unknown tag, treat as part of description or ignore?
+                # JSDoc usually keeps them or hides them. 
+                # For now let's append to description if it was checking description,
+                # or just ignore. 
+                # Let's treat unknown tags as description for now?
+                # Or skipping. Let's skip unknown tags for now to keep clean.
+                current_tag = 'unknown' 
+                current_buffer = [line]
+        else:
+            if current_tag != 'unknown':
+                current_buffer.append(line)
+            
+    flush()
+    
+    return '\n'.join(description_lines).strip(), params, returns

csdoc-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+csdoc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csdoc/cli.py,sha256=Ks92ORHTEjWpHTRMG-eshFTxyI8s_omklNoQlUbyHhk,1795
+csdoc/models.py,sha256=DWAomGgtm9xqE8C2uzvEpbXg84czzElXvw5WPO2DCFs,1380
+csdoc/generator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csdoc/generator/builder.py,sha256=8kGJACMw71Ldxn2NQqz4S4gHO86nEgvheDkOA2OkdJ4,2368
+csdoc/generator/templates/base.html,sha256=SIhX7yqPe5ZzKUxHSa3pwCxGdIhrLAvLitlW_W0fsDg,3817
+csdoc/generator/templates/index.html,sha256=gOns99jbRrOB0D6LQMAcDdBzIiLFgED5gVqSJnpu3Q8,4289
+csdoc/parser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csdoc/parser/csound.py,sha256=B9VK2mdBBIfLVeS_1ycvEJ20MLY9trXZwF1228NpaDY,8632
+csdoc/parser/docblock.py,sha256=cSkvUtl4N9aQCpHiFHRLE_MKfssW7XFknAXZX7gp1_s,4577
+csdoc-0.1.0.dist-info/METADATA,sha256=UKWsMxmUFY3TyoVVzncYtEzz5lOsGleug_8-asqA9h0,2771
+csdoc-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+csdoc-0.1.0.dist-info/entry_points.txt,sha256=8HboyOzdeu4iHcb9WtWRZQS5YoMtGn1ZOUZUgxeQfLY,40
+csdoc-0.1.0.dist-info/RECORD,,

csdoc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

csdoc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+csdoc = csdoc.cli:app