How the example uses sphinx-svdomain

The extension and source parser are enabled in docs/conf.py:

extensions = [
    "sphinx_svdomain",
    "sphinxcontrib.wavedrom",
]
sv_autodoc_backend = "pyslang"

Targeted autodoc

The API page uses a targeted directive when a source file contains one object that should be documented:

.. sv:automodule:: uart_rx
   :source: ../rtl/uart_rx.sv

sv:autopackage and sv:autointerface use the same pattern. When every supported top-level declaration in a file is wanted, sv:autofile accepts the source path as its argument.

Cross-references

Autodoc registers ordinary domain objects, so hand-written pages can link to generated modules, ports, parameters, and types:

:sv:mod:`uart_rx`
:sv:port:`uart_rx.rx_data`
:sv:param:`uart_reg_pkg::RxFifoDepth`
:sv:type:`uart_reg_pkg::uart_reg2hw_t`

Those roles produce links to uart_rx, uart_rx.rx_data, uart_reg_pkg::RxFifoDepth, and uart_reg_pkg::uart_reg2hw_t in this build.

Syntax-only boundary

Autodoc parses a file but does not elaborate the complete OpenTitan design. External types such as tlul_pkg::tl_h2d_t remain readable source text, and instances, procedural logic, and assertions are outside the current object model. The documentation-only rtl/prim_assert.sv shim supplies empty definitions for the assertion macros included by three UART files; it does not affect the UART logic and is never suitable for RTL builds.

The local UART files demonstrate all supported documentation-comment forms:

/**
 * @brief UART serial-to-parallel receive engine.
 * @port rx Asynchronous serial receive input.
 */
module uart_rx (...);

/// Receive break-detection state.
typedef enum logic {
  BRK_CHK, ///< Check received characters for a break condition.
  BRK_WAIT ///< Wait for the line to return high after a break.
} break_st_e;

The extension’s README lists all currently supported declaration kinds and autodoc limitations.