How the example uses sphinx-svdomain
====================================

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

.. code-block:: python

   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:

.. code-block:: rst

   .. 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:

.. code-block:: rst

   :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 :sv:mod:`uart_rx`,
:sv:port:`uart_rx.rx_data`, :sv:param:`uart_reg_pkg::RxFifoDepth`, and
:sv:type:`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:

.. code-block:: systemverilog

   /**
    * @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.

.. _README: https://github.com/HardMatrix/sphinx-svdomain#readme