Common Templates

This directory contains reusable reStructuredText (RST) templates for software tools documentation used across ADI reference designs.

Overview

The common templates provide standardized documentation sections for:

Necessary Files (necessary_files.rst.jinja) - Boot file requirements for each FPGA platform
IIO Oscilloscope (using-iio-osc.rst.jinja) - ADI IIO Oscilloscope application documentation
Scopy (using-scopy.rst.jinja) - Scopy software toolbox documentation

These templates are designed to be included in project-specific quickstart guides and user guides to maintain consistency across documentation.

necessary_files.rst.jinja

Description

This template generates the “Necessary files” section that lists the boot files required for a given FPGA platform. It handles differences between AMD and Intel families, Kuiper vs. non-Kuiper projects, and platform-specific build instructions.

Template Variables

Variable	Type	Description
`fpga_family`	string	Target FPGA family. Determines the boot file list, notes, and build instructions. Supported values: AMD: `zynq`, `zynqmp`, `versal`, `microblaze` Intel: `a10soc`, `cyclone5`, `agilex7soc`, `stratix10`
`hdl_project_doc`	string	HDL project documentation path for Sphinx cross-references (e.g., `adrv9009`, `ad9084`).
`in_kuiper`	boolean	Whether the project ships pre-built boot files on the Kuiper Linux SD card image. Defaults to `true`. Set to `false` for projects that are not part of the release. Note that `agilex7soc` and `stratix10` are never on Kuiper regardless of this flag.
`hdl_branch`	string	(Required if `in_kuiper` is `false`) HDL git branch path for the project (e.g., `projects/ad4080_fmc_evb`). Must be quoted if it contains YAML special characters (e.g., `:`).
`linux_branch`	string	(Required if `in_kuiper` is `false`) Linux git branch path for the project (e.g., `staging/ad4080_clean_adf4350:`). Must be quoted if it contains YAML special characters (e.g., `:`).
`carrier`	string	(Optional) Carrier board identifier. Currently used to add the System Controller SD card note for `vck190` and `vmk180` carriers.

Usage Example

.. include-template:: necessary_files.rst.jinja

   fpga_family: agilex7soc
   hdl_project_doc: ad9084

.. include-template:: necessary_files.rst.jinja

   fpga_family: versal
   hdl_project_doc: adrv9009
   carrier: vck190

.. include-template:: necessary_files.rst.jinja

   fpga_family: zynq
   hdl_project_doc: adrv9009
   in_kuiper: false
   hdl_branch: "projects/ad4080_fmc_evb"
   linux_branch: "staging/ad4080_clean_adf4350:"

using-iio-osc.rst.jinja

Description

This template provides documentation for the ADI IIO Oscilloscope application, a cross-platform tool for interfacing with IIO devices. It supports both Linux and no-OS environments.

Template Variables

Optional Variables

Variable	Type	Description
`has_linux`	boolean	Show Linux section (default: false)
`has_no_os`	boolean	Show no-OS section (default: false)
`has_local_connection`	boolean	Show “Locally run on the board” subsection under Linux (default: false, requires `has_linux`)
`show_linux_connection_image`	boolean	Show Linux connection image (default: false, requires `has_linux` and `linux_connection_image`)
`linux_connection_image`	path	Image showing IIO Oscilloscope connection (Linux only)
`show_no_os_connection_image`	boolean	Show no-OS connection image (default: false, requires `has_no_os` and `no_os_connection_image`)
`no_os_connection_image`	path	Image showing IIO Oscilloscope no-OS serial connection (requires `has_no_os` and `show_no_os_connection_image`)
`iio_has_plugin`	boolean	Enable plugin section
`iio_plugin_ref`	string	Reference to IIO plugin documentation (required if `iio_has_plugin` is true)
`iio_channel_description`	multiline string	Custom RST content for the “Channel Description” section, placed after Plugin and before Data capture. Use YAML multiline syntax (`\|`) to write content directly in the page.
`iio_show_data_capture`	boolean	Enable data capture section
`iio_show_time_domain`	boolean	Show time domain plot (requires `iio_show_data_capture`)
`iio_time_domain_image`	path	Time domain capture image (required if `iio_show_time_domain` is true)
`iio_show_frequency_domain`	boolean	Show frequency domain plot (requires `iio_show_data_capture`)
`iio_frequency_domain_image`	path	Frequency domain capture image (required if `iio_show_frequency_domain` is true)
`iio_data_captures`	list	List of data capture entries (requires `iio_show_data_capture`). Each entry has optional `title`, `time_domain_image`, and `frequency_domain_image` fields. Use this for multiple data capture groups with different titles and images.

Usage Example

For Linux only:

.. include-template:: ../../common/using-iio-osc.rst.jinja

   has_linux: true
   show_linux_connection_image: true
   linux_connection_image: ../images/ADRV9002_IIO_connection_zed.png
   iio_has_plugin: true
   iio_plugin_ref: adrv9002-plugin
   iio_show_data_capture: true
   iio_show_time_domain: true
   iio_time_domain_image: ../images/ADRV9002_time_domain.png
   iio_show_frequency_domain: true
   iio_frequency_domain_image: ../images/ADRV9002_frequency_domain.png

For both Linux and no-OS:

.. include-template:: ../../common/using-iio-osc.rst.jinja

   has_linux: true
   show_linux_connection_image: true
   linux_connection_image: ../images/ADRV9002_IIO_connection_zed.png
   has_no_os: true
   show_no_os_connection_image: true
   no_os_connection_image: ../images/ADRV9002_IIO_no_os_serial.png
   iio_has_plugin: true
   iio_plugin_ref: adrv9002-plugin
   iio_show_data_capture: true
   iio_show_time_domain: true
   iio_time_domain_image: ../images/ADRV9002_time_domain.png
   iio_show_frequency_domain: true
   iio_frequency_domain_image: ../images/ADRV9002_frequency_domain.png

With channel description:

.. include-template:: ../../common/using-iio-osc.rst.jinja

   has_linux: true
   has_no_os: true
   iio_channel_description: |
     Main receivers RX1 and RX2 are handled by the axi-ad9371-rx-hpc IIO
     device, while the observation is handled by the axi-ad9371-rx-obs-hpc
     device.

     Channels:

     .. list-table::
        :header-rows: 1

        * - IIO Device Channels
          - voltage0_i voltage0_q
          - voltage1_i voltage1_q
        * - axi-ad9371-rx-hpc
          - RX1
          - RX2
        * - axi-ad9371-rx-obs-hpc
          - OBS RX1
          -

With multiple data captures:

.. include-template:: ../../common/using-iio-osc.rst.jinja

   has_linux: true
   has_no_os: true
   iio_show_data_capture: true
   iio_data_captures:
     - title: Channel 1
       time_domain_image: ../images/ch1_time_domain.png
       frequency_domain_image: ../images/ch1_frequency_domain.png
     - title: Channel 2
       time_domain_image: ../images/ch2_time_domain.png
       frequency_domain_image: ../images/ch2_frequency_domain.png

Template Structure

The template generates different sections based on has_linux and has_no_os variables:

Common sections (always shown):

ADI IIO Oscilloscope - Introduction

For Linux (if ``has_linux: true``):

For Linux section containing:
- Remote run on host - Instructions for connecting from a host PC via IP (with optional connection image)
- Locally run on the board (if has_local_connection: true) - Instructions for running on the FPGA with HDMI monitor

For no-OS (if ``has_no_os: true``):

For no-OS section - Instructions for enabling IIOD with make flag

Optional sections:

Plugin (if iio_has_plugin: true) - Device-specific plugin information
Data capture (if iio_show_data_capture: true) - Time domain and/or frequency domain plots

using-scopy.rst.jinja

Description

This template provides documentation for Scopy, ADI’s cross-platform software toolbox for interfacing with ADI devices. It includes information about device connection methods, plugins, and data visualization.

Template Variables

Optional Variables

Variable	Type	Description
`scopy_has_plugin`	boolean	Enable plugin section
`scopy_plugin_path`	string	Path to Scopy plugin documentation (required if `scopy_has_plugin` is true)
`scopy_show_data_capture`	boolean	Enable data capture section
`scopy_show_time_domain`	boolean	Show time domain plot (requires `scopy_show_data_capture`)
`scopy_time_domain_image`	path	Time domain capture image (required if `scopy_show_time_domain` is true)
`scopy_show_frequency_domain`	boolean	Show frequency domain plot (requires `scopy_show_data_capture`)
`scopy_frequency_domain_image`	path	Frequency domain capture image (required if `scopy_show_frequency_domain` is true)

Usage Example

.. include-template:: ../../common/using-scopy.rst.jinja

   scopy_has_plugin: true
   scopy_plugin_path: plugins/adrv9002/adrv9002
   scopy_show_data_capture: true
   scopy_show_time_domain: true
   scopy_time_domain_image: ../images/ADRV9002_scopy_time_domain.png
   scopy_show_frequency_domain: true
   scopy_frequency_domain_image: ../images/ADRV9002_scopy_frequency_domain.png

Template Structure

The template generates the following sections:

Scopy - Introduction to Scopy toolbox
Connection Methods - General instructions on connecting devices:
- Automatic device scanning in home section
- Manual connection methods (IP, USB, serial port, URI)
- Example connection screenshots (hard-coded, not customizable)
Plugin (optional) - Device-specific plugin information with external link
Data capture (optional) - Time domain and/or frequency domain plots

Connection Methods

The template includes built-in documentation about Scopy connection methods:

Automatic scanning - Devices appear automatically when scan is ON
Manual connection - Via IP address, USB, serial port, or static/ dynamic URI
Connection images - Two reference images showing:
- Device scan interface (../../images/Scopy_connection1.png)
- Connection options interface (../../images/Scopy_connection2.png)

These images are hard-coded in the template and not customizable per project.

Path Conventions

Image paths should be relative to the file that includes the template
Use ../images/ for images in the project’s images folder
Connection images for Scopy use ../../images/ to reference common images in the reference-designs root

Notes

All boolean variables default to false if not specified
Image sections are only rendered if both the flag is true AND the image path is provided
Variable naming convention:
- IIO Oscilloscope variables: prefix with iio_ (e.g., iio_has_plugin, iio_show_data_capture)
- Scopy variables: prefix with scopy_ (e.g., scopy_has_plugin, scopy_show_data_capture)

Plugin Path Formats

IIO Oscilloscope Plugin Reference

Uses internal Sphinx reference: :ref:`{{ iio_plugin_ref }}`
Example: iio_plugin_ref: adrv9002-plugin

Scopy Plugin Path

Uses external documentation link: :external+scopy:doc:`here <{{ scopy_plugin_path }}>`
Path should be relative to Scopy documentation root
Example: scopy_plugin_path: plugins/adrv9002/adrv9002
Generates link to: https://analogdevicesinc.github.io/scopy/plugins/adrv9002/adrv9002.html

Example Integration

These templates are typically included in quickstart guides. See the zed.rst template for a complete integration example:

.. include-template:: ../../common/using-iio-osc.rst.jinja
   os_type: linux
   linux_connection_image: ../images/ADRV9002_IIO_connection_zed.png
   iio_has_plugin: true
   iio_plugin_ref: adrv9002-plugin

.. include-template:: ../../common/using-scopy.rst.jinja
   scopy_has_plugin: true
   scopy_plugin_path: plugins/adrv9002/adrv9002

This creates documentation for both IIO Oscilloscope and Scopy in sequence.