svdoc 0.1.0__tar.gz

svdoc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 svdoc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

svdoc-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: svdoc
+Version: 0.1.0
+Summary: pydoc-style documentation generator for SystemVerilog RTL
+License: MIT License
+        
+        Copyright (c) 2026 svdoc contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyslang>=11.0.0
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# svdoc
+
+A pydoc-style documentation generator for SystemVerilog RTL, built on
+[`pyslang`](https://pypi.org/project/pyslang/) (Python bindings for the
+`slang` SystemVerilog compiler).
+
+Extracts Doxygen-style doc comments (`/** @brief ... */`, `///< ...`) from
+modules, interfaces, and packages, and renders clean Markdown or HTML
+documentation — no manual editing required.
+
+## What it documents today
+
+- **Modules** — name, parameters, ports, doc comments
+- **Interfaces** — parameters, ports, signals, modports
+- **Packages** — typedefs (enums, packed structs, aliases), functions, tasks
+- **Cross-file type resolution** — a module's port typed from a package in
+  another file resolves to its fully-qualified `package::type` name
+
+Not yet supported: classes/UVM, instantiation hierarchy, block diagrams, full
+multi-file `` `include`` resolution.
+
+## Install
+
+```
+pip install svdoc
+```
+
+## Usage
+
+```
+# print Markdown to stdout
+svdoc my_module.sv
+
+# write a .md or .html file instead
+svdoc my_module.sv --out md
+svdoc my_module.sv --out html
+
+# resolve cross-file types (e.g. a module using a package's enum/struct)
+svdoc my_module.sv my_package.sv --out html
+
+# auto-scaffold missing doc comments in place (like `ruff --fix`)
+svdoc my_module.sv --fix
+
+# build a full linked HTML site from many files (any directory layout)
+svdoc build my_module.sv my_interface.sv my_package.sv --out-dir site/
+```
+
+## Doc comment convention
+
+Doxygen-style, both forms supported:
+
+```systemverilog
+/**
+ * @brief A simple synchronous FIFO.
+ */
+module fifo #(
+    parameter int DEPTH = 16  ///< Number of entries in the FIFO
+) (
+    input logic clk  ///< Clock
+);
+```
+
+## Development
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,docs]"
+python -m pytest
+```
+
+## License
+
+MIT — see `LICENSE`.

svdoc-0.1.0/README.md

@@ -0,0 +1,74 @@
+# svdoc
+
+A pydoc-style documentation generator for SystemVerilog RTL, built on
+[`pyslang`](https://pypi.org/project/pyslang/) (Python bindings for the
+`slang` SystemVerilog compiler).
+
+Extracts Doxygen-style doc comments (`/** @brief ... */`, `///< ...`) from
+modules, interfaces, and packages, and renders clean Markdown or HTML
+documentation — no manual editing required.
+
+## What it documents today
+
+- **Modules** — name, parameters, ports, doc comments
+- **Interfaces** — parameters, ports, signals, modports
+- **Packages** — typedefs (enums, packed structs, aliases), functions, tasks
+- **Cross-file type resolution** — a module's port typed from a package in
+  another file resolves to its fully-qualified `package::type` name
+
+Not yet supported: classes/UVM, instantiation hierarchy, block diagrams, full
+multi-file `` `include`` resolution.
+
+## Install
+
+```
+pip install svdoc
+```
+
+## Usage
+
+```
+# print Markdown to stdout
+svdoc my_module.sv
+
+# write a .md or .html file instead
+svdoc my_module.sv --out md
+svdoc my_module.sv --out html
+
+# resolve cross-file types (e.g. a module using a package's enum/struct)
+svdoc my_module.sv my_package.sv --out html
+
+# auto-scaffold missing doc comments in place (like `ruff --fix`)
+svdoc my_module.sv --fix
+
+# build a full linked HTML site from many files (any directory layout)
+svdoc build my_module.sv my_interface.sv my_package.sv --out-dir site/
+```
+
+## Doc comment convention
+
+Doxygen-style, both forms supported:
+
+```systemverilog
+/**
+ * @brief A simple synchronous FIFO.
+ */
+module fifo #(
+    parameter int DEPTH = 16  ///< Number of entries in the FIFO
+) (
+    input logic clk  ///< Clock
+);
+```
+
+## Development
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,docs]"
+python -m pytest
+```
+
+## License
+
+MIT — see `LICENSE`.

svdoc-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "svdoc"
+version = "0.1.0"
+description = "pydoc-style documentation generator for SystemVerilog RTL"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+dependencies = ["pyslang>=11.0.0"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+docs = ["sphinx", "sphinx-rtd-theme"]
+dev = ["ruff", "pytest"]
+
+[project.scripts]
+svdoc = "svdoc.cli:main"
+
+[tool.setuptools]
+packages = ["svdoc"]

svdoc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

svdoc-0.1.0/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-0.1.0/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-0.1.0/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