Documenting SystemVerilog should be straightforward, but finding a tool that matches the job is surprisingly difficult. SystemVerilog source already contains the structure we need to describe an API. The missing piece is a system that understands and preserves that structure.
The process becomes painful when the tool adds work instead of removing it. The reality is that documentation which is difficult to maintain will eventually drift from the design or be skipped altogether.
Today we are making sphinx-svdomain public. It is our new Sphinx domain for documenting SystemVerilog APIs, by hand or directly from source.
Why Sphinx fits the problem
We needed more than rendered source or a collection of standalone pages. We needed a system that could understand SystemVerilog declarations and preserve the relationships between them.
Sphinx was a strong contender because its domain system already provides this model for multiple languages. It ships with dedicated domains for Python, C, C++, and JavaScript. Each has its own object vocabulary and rules for resolving references. That maturity gave us a way to add SystemVerilog as a language in Sphinx without rebuilding the surrounding documentation infrastructure.
Previous attempts left the gap open
The idea of a Verilog domain for Sphinx is not new. The SymbiFlow sphinx-verilog-domain project established useful concepts around modules, ports, parameters, nesting, and references. But its last PyPI release was published in September 2020, its repository has not changed since March 2021, and its own documentation still describes the extension as under development. Its public usage also remains centered on a narrow Verilog subset.
A newer package called sphinx-doc appeared in late 2025 with broader SystemVerilog documentation claims. Its published requirements still depend on the 2020 sphinx-verilog-domain, however, and the source repository linked from its package metadata is no longer available. That makes the implementation difficult to inspect, maintain, or use as a dependable open source foundation.
These projects show that the need is real and that we are not alone in seeing it.
What we are releasing
The first public sphinx-svdomain release supports manual documentation and autodoc generated from source. Its current object model covers modules, interfaces, packages, parameters, localparams, ports, typedefs, enums and their values, structs, unions, fields, and functions.
Those declarations become Sphinx objects rather than formatted text fragments. They can appear in search and indexes, carry stable targets, resolve scoped references, and enter objects.inv for links between documentation sets. Source comments can become descriptions, while manual directives remain available when a project needs explanatory material that does not belong in the SystemVerilog source.
The autodoc path is intentionally honest about its current boundary. This alpha analyzes syntax only. It does not elaborate a design or claim complete coverage of every SystemVerilog construct. Unsupported areas are listed openly in the repository README.
Before opening the repository, we exercised the extension against large SystemVerilog codebases rather than only small fixtures. The release candidate has 137 automated tests, Sphinx builds that treat warnings as errors, package checks, and validation of installed wheels across Python 3.12, 3.13, and 3.14.
Why we made it public
Documentation tooling is shared infrastructure. Keeping this extension private would mean every team facing the same gap would either accept weaker documentation or build another local solution. Neither outcome helps the hardware ecosystem bring documentation up to the standard already expected from design and verification.
This is an initial alpha, and we invite you to help shape it. Use it on your SystemVerilog projects, test it, open issues, and suggest the changes you would like to see.