Cross-references

PeakRDL cross-references allow you to insert links into your documentation that point to specific register model nodes. These are very useful in programming guides, or more long-form prose in documentation.

Cross-references can link to inline register reference content, or dynamic HTML content.

:rdl:ref:

Insert an inline cross-reference link to an existing register reference node.

The contents of the link text can be controlled in several ways:

• :rdl:ref:`path.to.my_block.my_register` Results in the full link text: path.to.my_block.my_register

• :rdl:ref:`~path.to.my_block.my_register` Truncates text to only show the last segment: my_register

• :rdl:ref:`path.to.|my_block.my_register` Truncates everything before the |: my_block.my_register

• :rdl:ref:`My Awesome Register <path.to.my_block.my_register>` displays custom text: My Awesome Register

Whether the link points to PeakRDL-HTML reference, or an inline rdl:docnode depends on the peakrdl_default_link_to setting.

:rdl:html-ref:

Same as the rdl:ref role, except this will prefer linking to PeakRDL-HTML reference, regardless of the peakrdl_default_link_to setting.

:rdl:doc-ref:

Same as the rdl:ref role, except this will prefer linking to an inline docnode, regardless of the peakrdl_default_link_to setting.

.. rdl:relative-to:: path

It can be cumbersome to always specify the full register hierarchy in your docs. This directive lets you temporarily set a more localized scope to a hierarchy to make following references in the same document easier to manage.

Annoying! :rdl:ref:`very.long.path.to.my_block.my_register`

.. rdl:relative-to:: very.long.path.to

Much better! :rdl:ref:`my_block.my_register`

Cross-references will first search relative to the path specified, then fall back to searching the absolute path.