Custom roles

Doctools custom Sphinx roles allow better linking, such as git links, and formatting, like font coloring.

Below, every added role is explained with examples.

Note

Link-like roles use the :role:`text <link>` synthax, like external links, but without the undescore in the end.

Color

To print text in red or green, use :red:`text` and :green:`text`.

Link

The link roles are a group of roles defined by adi_links.py.

The validate_links global option is used to validate each link during build. These links are not managed, that means, only links from changed files are checked. You can run a build with it set to False, then touch the desired files to check the links of only these files.

Git

The Git role allows to create links to the Git repository with a shorter syntax. The role syntax is :git-repo:`text <type+branch:path>`, for example:

• :git-hdl:`main:docs/user_guide/docs_guidelines.rst` renders as docs/user_guide/docs_guidelines.rst.

• :git-hdl:`Guidelines <docs/user_guide/docs_guidelines.rst>` renders as Guidelines.

• :git-wiki-scripts:`raw+linux/build_zynq_kernel_image.sh`` renders as linux/build_zynq_kernel_image.sh.

Important

The repository name is case sensitive.

When the branch field is not present, it will be filled with the current branch. It is recommended to not provide this field when it is a link to its own repository, because it is useful to auto-fill it for documentation releases (e.g. hdl_2023_r2). A scenario where it is recommended to provide the branch is when linking others repositories.

They type field is also optional and the values are:

• gui: To view rendered on the Git server web GUI [default].

• raw: To download/view as raw.

• {}: Any other Git server web GUI link, e.g. :git-hdl:`releases+`. The last character must be +, since filenames/path may contain this character also.

The text field is optional and will be filled with the full path.

Finally, you can do :git-repo:`/` for a link to the root of the repository with pretty naming, for example, :git-hdl:`/` is rendered as ADI HDL repository.

DownGit

Same as the Git but wrapping the address with the ADI DownGit repository fork.

ADI

The adi role creates links for a webpage to the Analog Devices Inc. website.

The role syntax is :adi:`text <webpage>`, for example, :adi:`AD7175-2 <ad7175-2>`. Since links are case insensitive, you can also reduce it to :adi:`AD7175-2`, when webpage is the same as text and will render as AD7175-2.

Dokuwiki

The dokuwiki role creates links to the Analog Devices Inc. wiki website. The role syntax is :dokuwiki:`text <path>`, for example, :dokuwiki:`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>` gets rendered as pulsar-adc-pmods.

For intentional deprecated links, add the deprecated qualifier, e.g.: :dokuwiki+deprecated:`ADS-B Airplane Tracking Example <resources/tools-software/linux-software/libiio/clients/adsb_example>` gets rendered as ADS-B Airplane Tracking Example. The sole intend of this qualifier is to distinct pending import pages from won’t import pages.

EngineerZone

The ez role creates links to the Analog Devices Inc. EngineerZone support website. The role syntax is :ez:`community`, for example, :ez:`fpga` gets rendered as EngineerZone.

For Linux Software Drivers, it is :ez:`linux-software-drivers`.

For Microcontroller no-OS Drivers it is :ez:`microcontroller-no-os-drivers`.

Vendor

The vendor role creates links to the vendor’s website. The role syntax is :vendor:`text <path>`, for example, :xilinx:`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>` gets rendered Zynq-7000 SoC Overview.

The text parameter is optional, if absent, the file name will be used as the text, for example, :intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html` gets rendered general-purpose-i-o-overview.html (not very readable).

Supported vendors are: xilinx (AMD Xilinx), intel (Intel Altera) and mw (MathWorks).

Supplier

The supplier role creates links to a vendor’s website search. The role syntax is :vendor:`text <path>`, for example, :digikey:`AD9081-FMCA-EBZ` gets rendered AD9081-FMCA-EBZ.

The text parameter is optional.

Supported vendors are: digikey (Digikey), mouser (Mouser) and arrow (Arrow).