svdoc 0.1.0__py3-none-any.whl

svdoc/build.py

@@ -0,0 +1,71 @@
+"""svdoc build: a flat multi-page HTML site (one page per construct) with a
+navigable index, so cross-links between pages always resolve correctly --
+avoids the relative-path problem of generating standalone pages into
+whatever directories the source files happen to live in.
+"""
+
+import pathlib
+import re
+from html import escape
+
+from . import render_html
+from .ir import InterfaceDoc, ModuleDoc, PackageDoc
+from .parser import parse_file, resolve_types
+
+_UNSAFE_NAME_CHARS = re.compile(r"[^\w.-]")
+
+
+def _safe_page_name(name: str) -> str:
+    """Sanitize a construct name for use as an output filename. SV escaped
+    identifiers (``\\../../foo``) parse without error and can contain path
+    separators, so page filenames can't trust ``doc.name`` directly."""
+    return _UNSAFE_NAME_CHARS.sub("_", name)
+
+_RENDERERS = {
+    ModuleDoc: render_html.render,
+    InterfaceDoc: render_html.render_interface,
+    PackageDoc: render_html.render_package,
+}
+_KIND_LABELS = {
+    ModuleDoc: "Module",
+    InterfaceDoc: "Interface",
+    PackageDoc: "Package",
+}
+
+
+def build_site(paths: list, out_dir: str) -> str:
+    """Parse every file in ``paths`` and write one HTML page per construct
+    into a single flat ``out_dir``, plus an ``index.html`` linking to all of
+    them. Because every page lands in the same directory, the convention-based
+    cross-links in :mod:`svdoc.render_html` (``pkg_name.html#member``) always
+    resolve correctly, regardless of where the source ``.sv`` files live.
+
+    :param paths: All ``.sv`` files to document. Each is parsed independently
+        (one construct per file, same as :func:`svdoc.parser.parse_file`);
+        cross-file type resolution runs against the full set for every module.
+    :param out_dir: Directory to write the site into. Created if missing.
+    :returns: Path to the written ``index.html``.
+    :raises ValueError: If any file fails to parse cleanly.
+    """
+    out = pathlib.Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    docs = [parse_file(p) for p in paths]
+    for doc in docs:
+        if isinstance(doc, ModuleDoc):
+            resolve_types(doc, paths)
+
+    index_lines = ["<h1>svdoc site</h1>", "<ul>"]
+    for doc in sorted(docs, key=lambda d: (_KIND_LABELS[type(d)], d.name)):
+        page_name = f"{_safe_page_name(doc.name)}.html"
+        (out / page_name).write_text(_RENDERERS[type(doc)](doc))
+        label = _KIND_LABELS[type(doc)]
+        index_lines.append(
+            f'<li>{label}: <a href="{escape(page_name)}">{escape(doc.name)}</a></li>'
+        )
+    index_lines.append("</ul>")
+
+    index_html = render_html.page("svdoc site", index_lines)
+    index_path = out / "index.html"
+    index_path.write_text(index_html)
+    return str(index_path)

svdoc/cli.py

@@ -0,0 +1,123 @@
+"""svdoc CLI (v1): `svdoc <file.sv>` prints to terminal; `--out md`/`--out html`
+writes a file; `svdoc build <files...>` writes a multi-page linked HTML site.
+"""
+
+import argparse
+import pathlib
+import sys
+
+from . import render_html, render_md
+from .build import build_site
+from .fixer import fix_file
+from .ir import InterfaceDoc, ModuleDoc, PackageDoc
+from .parser import parse_file, resolve_types
+
+_RENDERERS = {
+    "md": {
+        ModuleDoc: render_md.render,
+        InterfaceDoc: render_md.render_interface,
+        PackageDoc: render_md.render_package,
+    },
+    "html": {
+        ModuleDoc: render_html.render,
+        InterfaceDoc: render_html.render_interface,
+        PackageDoc: render_html.render_package,
+    },
+}
+_EXTENSIONS = {"md": ".md", "html": ".html"}
+
+
+def _run_single(args):
+    if args.fix:
+        changed = fix_file(args.file)
+        print(f"{'fixed' if changed else 'no changes needed for'} {args.file}")
+        return
+
+    doc = parse_file(args.file)
+    if args.more_files and isinstance(doc, ModuleDoc):
+        resolve_types(doc, [args.file] + args.more_files)
+
+    if args.out:
+        text = _RENDERERS[args.out][type(doc)](doc)
+        out_path = pathlib.Path(args.file).with_suffix(_EXTENSIONS[args.out])
+        out_path.write_text(text)
+        print(f"wrote {out_path}")
+    else:
+        print(_RENDERERS["md"][type(doc)](doc))
+
+
+def _run_build(args):
+    index_path = build_site(args.files, args.out_dir)
+    print(f"wrote {len(args.files)} file(s) to a site at {index_path}")
+
+
+def _build_parser():
+    ap = argparse.ArgumentParser(prog="svdoc build")
+    ap.add_argument("files", nargs="+", help=".sv files to document")
+    ap.add_argument("--out-dir", required=True, help="directory to write the site into")
+    return ap
+
+
+def _single_parser():
+    ap = argparse.ArgumentParser(
+        prog="svdoc",
+        epilog="Also available: `svdoc build <files...> --out-dir <dir>` to "
+        "generate a multi-page linked HTML site.",
+    )
+    ap.add_argument(
+        "file",
+        help="path to the .sv file containing the module/interface/package to document",
+    )
+    ap.add_argument(
+        "more_files",
+        nargs="*",
+        help="additional .sv files (e.g. packages it depends on) used only to "
+        "resolve cross-file types -- not documented themselves",
+    )
+    ap.add_argument(
+        "--out",
+        choices=["md", "html"],
+        help="write rendered doc to a file in this format instead of printing to stdout",
+    )
+    ap.add_argument(
+        "--fix",
+        action="store_true",
+        help="insert ///< TODO stubs next to undocumented ports/params in place",
+    )
+    return ap
+
+
+def main(argv=None):
+    """Entry point for the ``svdoc`` command (registered via ``pyproject.toml``).
+
+    Two modes, dispatched on whether the first argument is the literal
+    ``build`` subcommand (argparse subparsers don't mix cleanly with a
+    same-position positional argument, so this is checked manually rather
+    than via ``add_subparsers``):
+
+    - ``svdoc <file.sv> [more_files...]`` — document a single module/interface/
+      package, optionally resolving cross-file types against ``more_files``,
+      printing Markdown to stdout or writing a single Markdown/HTML file
+      (``--out``), or scaffolding missing doc comments in place (``--fix``).
+    - ``svdoc build <files...> --out-dir <dir>`` — document every given file
+      into a single flat multi-page HTML site (one page per construct plus
+      an ``index.html``), so cross-links between pages always resolve
+      correctly regardless of where the source files live on disk.
+
+    :param argv: Argument list to parse (as :func:`sys.argv`\\ ``[1:]`` would
+        appear). Defaults to ``sys.argv[1:]`` when ``None``.
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if argv and argv[0] == "build":
+        args = _build_parser().parse_args(argv[1:])
+        _run_build(args)
+        return
+
+    args = _single_parser().parse_args(argv)
+    _run_single(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

svdoc/fixer.py

@@ -0,0 +1,91 @@
+"""svdoc --fix: insert `///< TODO` next to undocumented ports/params, and a
+`/** @brief TODO */` stub above an undocumented module, in place. Mirrors
+`ruff --fix` — scaffolds missing docs rather than guessing their content.
+"""
+
+import pyslang
+
+from .parser import _leading_doc, _trailing_doc
+
+
+def _end_offset(node) -> int:
+    """node may be a raw Token (comma, closing paren) or a syntax node."""
+    tok = node.getLastToken() if hasattr(node, "getLastToken") else node
+    return tok.range.end.offset
+
+
+def fix_file(path: str) -> bool:
+    """Scaffold missing doc comments in place, in ``path``, and save the result.
+
+    Inserts ``///< TODO`` next to any undocumented port/parameter, and a
+    ``/** @brief TODO */`` stub above the module/interface/package itself if
+    it has no doc comment. Idempotent: re-running on an already-documented
+    file makes no changes.
+
+    :param path: Path to the ``.sv`` file to fix in place.
+    :returns: ``True`` if the file was modified, ``False`` if it was already
+        fully documented.
+    :raises ValueError: If the file fails to parse cleanly.
+    """
+    tree = pyslang.syntax.SyntaxTree.fromFile(path, pyslang.SourceManager())
+    if tree.diagnostics:
+        raise ValueError(f"parse errors in {path}: {list(tree.diagnostics)}")
+
+    # module and interface declarations share the same syntax shape
+    # (ModuleDeclarationSyntax, differentiated only by .kind) -- --fix scaffolds
+    # their header (params/ports) doc comments identically. Body constructs
+    # (interface signals/modports) aren't scaffolded here yet.
+    mod = next(m for m in tree.root.members if hasattr(m, "header"))
+    header = mod.header
+
+    # (offset, text_to_insert), applied back-to-front so earlier offsets stay valid.
+    insertions = []
+
+    if _leading_doc(mod) is None:
+        offset = mod.getFirstToken().range.start.offset
+        insertions.append((offset, "/**\n * @brief TODO\n */\n"))
+
+    if header.parameters:
+        raw = list(header.parameters.declarations)
+        for i, node in enumerate(raw):
+            if node.kind != pyslang.syntax.SyntaxKind.ParameterDeclaration:
+                continue
+            has_comma = i + 1 < len(raw)
+            # trailing ///< doc for this item is leading trivia on the node
+            # AFTER its separator (see parser._trailing_doc) -- for the last
+            # item there's no comma, so the lookup and insertion point are
+            # both the item itself, right before the closing paren.
+            lookup = (
+                raw[i + 2]
+                if has_comma and i + 2 < len(raw)
+                else header.parameters.closeParen
+            )
+            if _trailing_doc(lookup) is None:
+                offset = _end_offset(raw[i + 1]) if has_comma else _end_offset(node)
+                insertions.append((offset, "  ///< TODO"))
+
+    if header.ports:
+        raw = list(header.ports.ports)
+        for i, node in enumerate(raw):
+            if not hasattr(node, "declarator"):
+                continue
+            has_comma = i + 1 < len(raw)
+            lookup = (
+                raw[i + 2]
+                if has_comma and i + 2 < len(raw)
+                else header.ports.closeParen
+            )
+            if _trailing_doc(lookup) is None:
+                offset = _end_offset(raw[i + 1]) if has_comma else _end_offset(node)
+                insertions.append((offset, "  ///< TODO"))
+
+    if not insertions:
+        return False
+
+    with open(path) as f:
+        text = f.read()
+    for offset, snippet in sorted(insertions, reverse=True):
+        text = text[:offset] + snippet + text[offset:]
+    with open(path, "w") as f:
+        f.write(text)
+    return True

svdoc/ir.py

@@ -0,0 +1,166 @@
+"""Doc IR (v1): module-level only. See PLAN.md Phase 1."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class Param:
+    """A single module/interface/subroutine parameter.
+
+    :ivar name: Parameter identifier.
+    :ivar type: Declared type as written in source (e.g. ``"int"``).
+    :ivar default: Default value expression, or ``None`` if unset.
+    :ivar doc: Extracted doc comment, or ``None`` if undocumented.
+    :ivar type_ref: Fully-qualified ``"package::type"`` name if resolved
+        cross-file via :func:`svdoc.parser.resolve_types`; ``None`` otherwise.
+    """
+
+    name: str
+    type: str
+    default: Optional[str]
+    doc: Optional[str]
+    type_ref: Optional[str] = None
+
+
+@dataclass
+class Port:
+    """A single module/interface/subroutine port or argument.
+
+    Also reused for subroutine arguments (see :attr:`Subroutine.args`), since
+    the shape (name, direction, type, doc) is identical.
+
+    :ivar name: Port identifier.
+    :ivar direction: ``"input"``, ``"output"``, ``"inout"``, etc.
+    :ivar type: Declared type as written in source, including any packed
+        dimensions (e.g. ``"logic [7:0]"``).
+    :ivar doc: Extracted doc comment, or ``None`` if undocumented.
+    :ivar type_ref: Fully-qualified ``"package::type"`` name if resolved
+        cross-file via :func:`svdoc.parser.resolve_types`; ``None`` otherwise.
+    :ivar modport_preview: For an interface-typed port (``direction ==
+        "interface"``), the resolved :class:`Modport` from the interface file,
+        if it was found among the files passed to
+        :func:`svdoc.parser.resolve_types`; ``None`` otherwise.
+    """
+
+    name: str
+    direction: str
+    type: str
+    doc: Optional[str]
+    type_ref: Optional[str] = None
+    modport_preview: Optional["Modport"] = None
+
+
+@dataclass
+class ModuleDoc:
+    """Doc IR for a single SystemVerilog module."""
+
+    name: str
+    doc: Optional[str]
+    params: List[Param] = field(default_factory=list)
+    ports: List[Port] = field(default_factory=list)
+
+
+@dataclass
+class Signal:
+    """A variable declared in an interface body (outside any modport)."""
+
+    name: str
+    type: str
+    doc: Optional[str]
+
+
+@dataclass
+class ModportPortGroup:
+    """One direction-grouped clause within a modport, e.g. ``output valid, data``."""
+
+    direction: str
+    signals: List[str]
+    doc: Optional[str]
+
+
+@dataclass
+class Modport:
+    """A single ``modport`` declaration inside an interface."""
+
+    name: str
+    doc: Optional[str]
+    port_groups: List[ModportPortGroup] = field(default_factory=list)
+
+
+@dataclass
+class InterfaceDoc:
+    """Doc IR for a single SystemVerilog interface, including its modports."""
+
+    name: str
+    doc: Optional[str]
+    params: List[Param] = field(default_factory=list)
+    ports: List[Port] = field(default_factory=list)
+    signals: List[Signal] = field(default_factory=list)
+    modports: List[Modport] = field(default_factory=list)
+
+
+@dataclass
+class EnumValue:
+    """A single named value within an ``enum`` typedef."""
+
+    name: str
+    value: Optional[str]
+    doc: Optional[str]
+
+
+@dataclass
+class StructField:
+    """A single field within a packed ``struct`` typedef."""
+
+    name: str
+    type: str
+    doc: Optional[str]
+
+
+@dataclass
+class Typedef:
+    """A single ``typedef`` declared in a package: enum, packed struct, or alias.
+
+    :ivar kind: One of ``"enum"``, ``"struct"``, or ``"alias"`` — determines
+        which of ``base_type``/``values``, ``fields``, or ``alias_type`` is populated.
+    :ivar base_type: For ``kind="enum"``, the underlying integer type
+        (e.g. ``"logic [1:0]"``).
+    :ivar alias_type: For ``kind="alias"``, the type being aliased.
+    :ivar values: For ``kind="enum"``, the enum's named values in declaration order.
+    :ivar fields: For ``kind="struct"``, the struct's fields in declaration order.
+    """
+
+    name: str
+    doc: Optional[str]
+    kind: str
+    base_type: Optional[str] = None
+    alias_type: Optional[str] = None
+    values: List[EnumValue] = field(default_factory=list)
+    fields: List[StructField] = field(default_factory=list)
+
+
+@dataclass
+class Subroutine:
+    """A ``function`` or ``task`` declared in a package.
+
+    :ivar kind: ``"function"`` or ``"task"``.
+    :ivar return_type: Declared return type; always ``None`` for tasks.
+    :ivar args: Arguments, reusing :class:`Port`'s name/direction/type/doc shape.
+    """
+
+    name: str
+    doc: Optional[str]
+    kind: str
+    return_type: Optional[str] = None
+    args: List[Port] = field(default_factory=list)
+
+
+@dataclass
+class PackageDoc:
+    """Doc IR for a single SystemVerilog package: its typedefs and subroutines."""
+
+    name: str
+    doc: Optional[str]
+    typedefs: List[Typedef] = field(default_factory=list)
+    subroutines: List[Subroutine] = field(default_factory=list)