Configuring
===========

.. role:: code-py(code)
   :language: Python

.. note::
    Unless specified otherwise, all relative file paths used in config options
    are interpreted as relative to the enclosing ``conf.py``.



PeakRDL compilation settings
----------------------------

.. confval:: peakrdl_cfg_toml
    :type: :code-py:`str`

    Optional path to a PeakRDL configuration TOML file.
    This is equivalent to the ``peakrdl`` command-line tool's ``--peakrdl-cfg`` flag.

    If not specified, a PeakRDL TOML config file is discovered using the
    `same rules as the command-line tool <https://peakrdl.readthedocs.io/en/latest/configuring.html>`_.


.. confval:: peakrdl_input_files
    :type: :code-py:`list[str]`

    List of input files to process. Files shall be listed in dependency-order to
    ensure child components declared before instantiated.


.. confval:: peakrdl_incdirs
    :type: :code-py:`list[str]`

    List of additional include search paths.


.. confval:: peakrdl_parameters
    :type: :code-py:`dict[str, Any]`

    Dictionary of parameters to pass to the top-level component when elaborating.

    Example:

    .. code-block:: python

        peakrdl_parameters = {
            "N_CHANNELS": 16,
            "BLOCK_VERSION_STR": "v1.2.3",
        }


.. confval:: peakrdl_defines
    :type: :code-py:`dict[str, str|None]`

    Dictionary of verilog-style define macros to inject into the SystemRDL
    preprocesor namespace.

    Assigning a macro :code-py:`None` is acceptable if novalue is needed.

    Example:

    .. code-block:: python

        peakrdl_defines = {
            "FOO": "asdf",
            "BAR": None,
        }


.. confval:: peakrdl_top_component
    :type: :code-py:`str`

    Explicitly choose which addrmap in the root namespace will be the top-level
    component. If unset, The last addrmap defined will be chosen.



Cross-reference settings
------------------------

.. confval:: peakrdl_default_link_to
    :type: :code-py:`str`
    :default: :code-py:`"html"`

    Configures what the default behavior is for register map cross-references.
    If not explicitly specified, behavior is determined by this setting.

    "html"
        Link to PeakRDL-HTML output
    "doc"
        Link to an inline documentation reference generated by either the
        :rst:dir:`rdl:docnode` or :rst:dir:`rdl:doctree` directives.

    .. note::
        If "doc" is selected, but a corresponding target node was never inserted
        using :rst:dir:`rdl:docnode` or :rst:dir:`rdl:doctree`, the reference
        will attempt to link to the PeakRDL html output if available.



PeakRDL-HTML output settings
----------------------------
.. confval:: peakrdl_html_enable
    :type: :code-py:`str`
    :default: :code-py:`True`

.. confval:: peakrdl_html_title
    :type: :code-py:`str`

    Override the title text for the PeakRDL-HTML output.

.. confval:: peakrdl_html_extra_doc_properties
    :type: :code-py:`list[str]`

    List of additional properties to explicitly document.

    Nodes that have a property explicitly set will show its value in a table in
    the node's description. Use this to bring forward user-defined properties,
    or other built-in properties in your documentation.



Inline docnode/doctree settings
-------------------------------

.. confval:: peakrdl_doc_wrap_section
    :type: :code-py:`bool`
    :default: :code-py:`True`

    Whether to wrap :rst:dir:`rdl:docnode` output in a section heading.

    Configures the default behavior for all :rst:dir:`rdl:docnode` directives.
    If not explicitly specified, behavior is determined by this setting.

    .. note::
        Cross-references will not be able to link to a :rst:dir:`rdl:docnode` if
        it is not wrapped in a section heading.
