docs: links, drop part, fixups, codeowners

Drop part role, use generic adi instead for root adi domain links.
For future reference, the snipped used was:
find ./docs/projects -type f -exec sed -i 's/:part:/:adi:/g' {} \;
Drop Containerfile.
Add option to validate links status (e.g. 200, 404), intended mostly for CI
use to check if a page has disappeared from the internet.
Validate links uses coroutines to launch multiple tasks concurrently,
but do it in bundles to avoid being rate limited.
Fixup regmap styling.
Add imoldovan, jmarques, spop, lbarbosa as docs codeowners.
Remove branch field for links to the hdl repo.
Change git role to display full path.
Fixup ZedBoard link label, remove IP List, add SYSID_ROM dokuwiki link
in ad716_sdz project.

Signed-off-by: Jorge Marques <jorge.marques@analog.com>

.github/CODEOWNERS

@@ -215,3 +215,6 @@
 
 # Code owners for jesd204  IP
 /library/jesd204/           ionut.podgoreanu@analog.com  adrian.costina@analog.com
+
+# Code owners for docs
+/docs/                      iulia.moldovan@analog.com  jorge.marques@analog.com  stanca.pop@analog.com  laez.barbosa@analog.com

docs/Containerfile

@@ -1,36 +0,0 @@
-FROM registry.gitlab.com/islandoftex/images/texlive:TL2022-2022-12-25-full
-
-SHELL ["/bin/bash", "-c"]
-
-ENV HOME /root
-
-ARG DEBIAN_FRONTEND=noninteractive
-ENV TZ=Europe/Bucharest
-
-ENV PROJ hdl-docs
-
-RUN apt-get update
-
-RUN apt-get -y --no-install-recommends install \
-    python3 python3-venv python3-pip
-
-# To convert svg to pdf, used in sphinx->LaTeX->pdf pipeline
-RUN apt-get -y --no-install-recommends install \
-    librsvg2-bin
-
-RUN python3 -m venv /opt/venv
-
-COPY requirements.txt .
-
-RUN source /opt/venv/bin/activate ; \
-    pip3 install -U pip
-
-RUN source /opt/venv/bin/activate ; \
-    pip3 install wheel vext vext.gi
-
-RUN source /opt/venv/bin/activate ; \
-    pip3 install -r requirements.txt ; \
-    deactivate
-
-RUN mkdir -p /usr/local/bin ; \
-    ln -s /opt/venv/bin/symbolator /usr/local/bin/symbolator

docs/conf.py

@@ -32,6 +32,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # -- Custom extensions configuration -------------------------------------------
 
 hide_collapsible_content = True
+validate_links = False
 
 # -- todo configuration -------------------------------------------------------
 

docs/extensions/adi_hdl_parser.py

@@ -75,16 +75,6 @@ def pretty_dep(string):
 		return ''
 	return string.replace("'MODELPARAM_VALUE.",'').replace("'",'')
 
-def sanitized_bool(string):
-	string_ = string.strip().lower()
-	if string_ in ['1', 'true', 'yes', 'y']:
-		return True
-	elif string_ in ['0', 'false', 'no', 'n']:
-		return False
-	else:
-		logger.warning(f"Got malformed bool value {string}.")
-		return False
-
 class directive_base(Directive):
 	has_content = True
 	add_index = True
@@ -118,6 +108,16 @@ class directive_base(Directive):
 			node.document = self.state.document
 			nested_parse_with_titles(self.state, rst, node)
 			entry += node
+		elif node_type == 'default_value':
+			if text[0:2] != '0x':
+				rst = ViewList()
+				rst.append(text, f"virtual_{str(uuid4())}", 0)
+				node = nodes.section()
+				node.document = self.state.document
+				nested_parse_with_titles(self.state, rst, node)
+				entry += node
+			else:
+				entry += nodes.literal(text=text)
 		else:
 			return
 		row += entry
@@ -380,7 +380,7 @@ class directive_regmap(directive_base):
 		table = nodes.table(classes=['regmap'])
 		table += tgroup
 
-		self.table_header(tgroup, ["DWORD", "BYTE", "BITS", "Name", "Type", "Default", "Description"])
+		self.table_header(tgroup, ["DWORD", "BYTE", "BITS", "Name", "Type", "Default Value", "Description"])
 
 		rows = []
 		for reg in obj['regmap']:
@@ -400,8 +400,8 @@ class directive_regmap(directive_base):
 					['', 'literal'],
 					[f"[{field['bits']}]", 'literal'],
 					[field['name'], 'literal'],
-					[field['rw'], 'paragraph'],
+					[field['rw'], 'literal'],
-					[field['default'], 'paragraph', ['default']],
+					[field['default'], 'default_value', ['default']],
 					[field['description'], 'reST', ['description']],
 				])
 
@@ -817,7 +817,7 @@ def parse_hdl_regmap(reg, ctime):
 				field_loc = data[fi + 1].strip()
 				field_loc = field_loc.split(" ")
 				field_bits = field_loc[0].replace("[", "").replace("]", "")
-				field_default = field_loc[1] if len(field_loc) > 1 else "NA"
+				field_default = ' '.join(field_loc[1:]) if len(field_loc) > 1 else "NA"
 
 				field_name = data[fi + 2].strip()
 				field_rw = data[fi + 3].strip()
@@ -839,6 +839,11 @@ def parse_hdl_regmap(reg, ctime):
 				field_desc = [data[fi].strip() for fi in range(fi + 4, efi)]
 				field_desc = " ".join(field_desc)
 
+				# TODO Remove dokuwiki scaping support
+				# Temporary dokuwiki scaping convert to not break current dokuwiki tables
+				field_default = field_default.replace("''", "``")
+				field_desc = field_desc.replace("''", "``")
+
 				fields.append(
 					{
 						"name": field_name,

docs/extensions/adi_links.py

@@ -1,20 +1,29 @@
 ###############################################################################
-## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
+## Copyright (C) 2023 Analog Devices, Inc. All rights reserved.
 ### SPDX short identifier: ADIBSD
 ###############################################################################
 
 from docutils import nodes
+from sphinx.util import logging
 import subprocess
+import asyncio
+import aiohttp
+
+logger = logging.getLogger(__name__)
+validate_links_user_agent = 'Status resolver (Python/Sphinx)'
 
 # Default values
 dft_url_datasheet = 'https://www.analog.com/media/en/technical-documentation/data-sheets/'
 dft_url_dokuwiki  = 'https://wiki.analog.com'
 dft_url_ez        = 'https://ez.analog.com'
+dft_url_mw        = 'https://www.mathworks.com'
 dft_url_git       = 'https://github.com/analogdevicesinc'
-dft_url_part		= 'https://www.analog.com'
+dft_url_adi       = 'https://www.analog.com'
 dft_url_xilinx    = 'https://www.xilinx.com'
 dft_url_intel     = 'https://www.intel.com'
 
+dft_validate_links = False
+
 git_repos = [
 	# url_path           name
 	['hdl',              "HDL"],
@@ -23,9 +32,10 @@ git_repos = [
 	['no-os',            "no-OS"],
 	['libiio',           "libiio"],
 	['scopy',            "Scopy"],
-	['iio-oscilloscope', "IIO Oscilloscope"]
+	['iio-oscilloscope', "IIO Oscilloscope"],
+	['pyadi-iio',        "PyADI-IIO"]
 ]
-vendors = ['xilinx', 'intel']
+vendors = ['xilinx', 'intel', 'mw']
 
 def get_url_config(name, inliner):
 	app = inliner.document.settings.env.app
@@ -50,7 +60,9 @@ def datasheet():
 			part_id = text[0:text.find(':')]
 			url = get_url_config('datasheet', inliner) + '/' + part_id + '.pdf#' + anchor
 		node = nodes.reference(rawtext, part_id + " datasheet", refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
+
 	return role
 
 def dokuwiki():
@@ -60,16 +72,24 @@ def dokuwiki():
 			text = path[path.rfind('/')+1:]
 		url = get_url_config('dokuwiki', inliner) + '/' + path
 		node = nodes.reference(rawtext, text, refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
+
 	return role
 
 def ez():
 	def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-		url = get_url_config('ez', inliner) + '/' + text
+		text, path = get_outer_inner(text)
-		node = nodes.reference(rawtext, "EngineerZone", refuri=url, **options)
+		if path == '/':
+			path = ''
+		url = get_url_config('ez', inliner) + '/' + path
+		if text is None:
+			text = "EngineerZone"
+		node = nodes.reference(rawtext, text, refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
-	return role
 
+	return role
 
 def get_active_branch_name():
 	branch = subprocess.run(['git', 'branch', '--show-current'], capture_output=True)
@@ -87,20 +107,24 @@ def git(repo, alt_name):
 			branch = get_active_branch_name() if pos in [0, -1] else path[0:pos]
 			path = path[pos+1:]
 			if text is None:
-				text = path[path.rfind('/')+1:]
+				text = path
 			url = url + '/blob/' + branch + '/' + path
 			node = nodes.reference(rawtext, text, refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
+
 	return role
 
-def part():
+def adi():
 	def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-		name, part_id = get_outer_inner(text)
+		name, adi_id = get_outer_inner(text)
 		if name is None:
-			name = part_id
+			name = adi_id
-		url = get_url_config('part', inliner) + '/' + part_id + '.html'
+		url = get_url_config('adi', inliner) + '/' + adi_id
 		node = nodes.reference(rawtext, name, refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
+
 	return role
 
 def vendor(vendor_name):
@@ -110,27 +134,118 @@ def vendor(vendor_name):
 			text = path[path.rfind('/')+1:]
 		url = get_url_config(vendor_name, inliner) + '/' + path
 		node = nodes.reference(rawtext, text, refuri=url, **options)
+		add_link(inliner, lineno, url)
 		return [node], []
+
 	return role
 
+def prepare_validade_links(app, env, docnames):
+	# Not managing links, so checking only changed files per build.
+	# A user can run a build with validate_links False, touch the
+	# desired files then run with validate_links True to check the links
+	# from only these files.
+	env.links = {}
+
+def validate_links(app, env):
+	if not env.config.validate_links:
+		logger.info(f"Skipping {len(env.links)} URLs checks-ups. Set validate_links to True to enable this.")
+		return
+
+	asyncio.run(
+		async_validate_links(app, env)
+	)
+
+async def validate_link(link, headers):
+	session_timeout = aiohttp.ClientTimeout(total=None, sock_connect=10, sock_read=10)
+	try:
+		async with aiohttp.ClientSession(timeout=session_timeout) as session:
+			async with session.get(link, headers=headers, timeout=10) as response:
+				return link, response.status
+	except aiohttp.ClientError as e:
+		return link, e
+	except asyncio.TimeoutError as e:
+		return link, e
+
+async def async_validate_links(app, env):
+	headers = {'User-Agent': validate_links_user_agent}
+
+	fail_count = 0
+	total = len(env.links)
+	completed = 0
+	tasks = []
+	results = []
+	step = 25
+
+	links = list(env.links)
+	leng = total%step+2 if total%step != 0 else total%step+1
+	for i in range(0, leng):
+		cur = i*step
+		end = total if (i+1)*step > total else (i+1)*step
+		_links = links[cur:end]
+		for link in _links:
+			task = asyncio.create_task(validate_link(link, headers))
+			tasks.append(task)
+
+		for task in asyncio.as_completed(tasks):
+			results.append(await task)
+			completed += 1
+			print(f'Validated URL {completed} out of {total}, bundle {i+1} of {leng}...', end='\r')
+		del tasks
+		tasks = []
+
+	for link, error in results:
+		if isinstance(error, asyncio.TimeoutError):
+			error = 'Timeout Error'
+		if error != 200:
+			fail_count += 1
+			if len(env.links[link]) > 1:
+				extended_error = f"Resolved {len(env.links[link])} times, path shown is the first instance."
+			else:
+				extended_error = ""
+			logger.warning(f"URL {link} returned {error}! {extended_error}", location=env.links[link][0])
+
+	if fail_count:
+		logger.warning(f"{fail_count} out of {len(env.links)} URLs resolved with an error ({fail_count/(len(env.links))*100:0.2f}%)!")
+	else:
+		if total == 0:
+			extended_info = "\nAt every build, only the links at files that changed are checked, consider touching them to re-check."
+		else:
+			extended_info = ""
+		logger.info(f"All {total} URLs resolved successfully.{extended_info}")
+
+
+def add_link(inliner, lineno, link):
+	links = inliner.document.settings.env.links
+	docname = (inliner.document.current_source[:-4],lineno)
+	if link not in links:
+		links[link] = [docname]
+	else:
+		links[link].append(docname)
+
 def setup(app):
 	app.add_role("datasheet",       datasheet())
 	app.add_role("dokuwiki",        dokuwiki())
 	app.add_role("ez",              ez())
-	app.add_role("part",            part())
+	app.add_role("adi",             adi())
 	for name in vendors:
 		app.add_role(name,          vendor(name))
 	for path, name in git_repos:
 		app.add_role("git-"+path,   git(path, name))
 
+	app.connect('env-before-read-docs', prepare_validade_links)
+	app.connect('env-updated', validate_links)
+
 	app.add_config_value('url_datasheet', dft_url_datasheet, 'env')
 	app.add_config_value('url_dokuwiki',  dft_url_dokuwiki,  'env')
 	app.add_config_value('url_ez',        dft_url_ez,        'env')
+	app.add_config_value('url_mw',        dft_url_mw,        'env')
 	app.add_config_value('url_git',       dft_url_git,       'env')
-	app.add_config_value('url_part',      dft_url_part,      'env')
+	app.add_config_value('url_adi',       dft_url_adi,       'env')
 	app.add_config_value('url_xilinx',    dft_url_xilinx,    'env')
 	app.add_config_value('url_intel',     dft_url_intel,     'env')
 
+	app.add_config_value('validate_links',dft_validate_links,'env')
+
 	return {
 		'version': '0.1',
 		'parallel_read_safe': True,

docs/library/axi_dmac/index.rst

@@ -56,7 +56,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/axi_dmac/axi_dmac.v`
+   * - :git-hdl:`library/axi_dmac/axi_dmac.v`
      - Verilog source for the peripheral.
 
 Block Diagram

docs/library/spi_engine/axi_spi_engine.rst

@@ -23,9 +23,9 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/axi_spi_engine/axi_spi_engine.v`
+   * - :git-hdl:`library/spi_engine/axi_spi_engine/axi_spi_engine.v`
      - Verilog source for the peripheral.
-   * - :git-hdl:`master:library/spi_engine/axi_spi_engine/axi_spi_engine_ip.tcl`
+   * - :git-hdl:`library/spi_engine/axi_spi_engine/axi_spi_engine_ip.tcl`
      - TCL script to generate the Vivado IP-integrator project for the peripheral.
 
 Configuration Parameters

docs/library/spi_engine/control-interface.rst

@@ -30,7 +30,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml`
+   * - :git-hdl:`library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml`
      - Interface definition file
 
 Signal Pins

docs/library/spi_engine/index.rst

@@ -75,14 +75,14 @@ Examples
 --------------------------------------------------------------------------------
 
 * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
-  Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC.
+  Colorimeter application using the :adi:`AD7175-2` Sigma-Delta ADC.
 * :dokuwiki:`resources/eval/user-guides/adaq7980-sdz`:
   A 16-bit ADC subsystem with four common signal processing and conditioning blocks.
 * :dokuwiki:`resources/tools-software/uc-drivers/ad5766`:
   16-channel, 16-/12-bit, voltage output Digital-to-Analog Converters (DAC).
 * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
   The AD7768-1 is a low power, high performance, Σ-Δ analog-to-digital converter (ADC).
-* :git-hdl:`master:projects/ad40xx_fmc`
+* :git-hdl:`projects/ad40xx_fmc`
   Evaluation Board for the AD4000 Series 16-/18-/20-Bit Precision SAR ADCs.
 * :dokuwiki:`AD469x <resources/eval/user-guides/ad469x>`:
   16-Bit, 16-Channel, 500 kSPS/1 MSPS, Easy Drive Multiplexed SAR ADC.

docs/library/spi_engine/offload-control-interface.rst

@@ -16,7 +16,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_offload_ctrl_rtl.xml`
+   * - :git-hdl:`library/spi_engine/interfaces/spi_engine_offload_ctrl_rtl.xml`
      - Interface definition file
 
 Signal Pins

docs/library/spi_engine/spi-bus-interface.rst

@@ -13,7 +13,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/interfaces/spi_master_rtl.xml`
+   * - :git-hdl:`library/spi_engine/interfaces/spi_master_rtl.xml`
      - Interface definition file
 
 Signal Pins

docs/library/spi_engine/spi_engine_execution.rst

@@ -19,9 +19,9 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution.v`
+   * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution.v`
      - Verilog source for the peripheral.
-   * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl`
+   * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl`
      - TCL script to generate the Vivado IP-integrator project for the peripheral.
 
 Configuration Parameters

docs/library/spi_engine/spi_engine_interconnect.rst

@@ -27,9 +27,9 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/spi_engine_interconnect/spi_engine_interconnect.v`
+   * - :git-hdl:`library/spi_engine/spi_engine_interconnect/spi_engine_interconnect.v`
      - Verilog source for the peripheral.
-   * - :git-hdl:`master:library/spi_engine/spi_engine_interconnect/spi_engine_interconnect_ip.tcl`
+   * - :git-hdl:`library/spi_engine/spi_engine_interconnect/spi_engine_interconnect_ip.tcl`
      - TCL script to generate the Vivado IP-integrator project for the
        peripheral.
 

docs/library/spi_engine/spi_engine_offload.rst

@@ -19,9 +19,9 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/spi_engine_offload/spi_engine_offload.v`
+   * - :git-hdl:`library/spi_engine/spi_engine_offload/spi_engine_offload.v`
      - Verilog source for the peripheral.
-   * - :git-hdl:`master:library/spi_engine/spi_engine_offload/spi_engine_offload_ip.tcl`
+   * - :git-hdl:`library/spi_engine/spi_engine_offload/spi_engine_offload_ip.tcl`
      - TCL script to generate the Vivado IP-integrator project for the
        peripheral.
 

docs/library/spi_engine/tutorial.rst

@@ -68,7 +68,7 @@ SPI Engine hierarchy instantiation
 
 The SPI Engine can be implemented in two ways, either by placing and connecting
 each IP individually or by using the function provided by the
-:git-hdl:`master:library/spi_engine/scripts/spi_engine.tcl` script.
+:git-hdl:`library/spi_engine/scripts/spi_engine.tcl` script.
 
 Using the script ensures that the correct connections are being made and that
 the IP cores will receive the correct parameter configuration since certain

docs/library/template_framework/index.rst

@@ -42,7 +42,7 @@ Examples
 --------------------------------------------------------------------------------
 
 * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
-  Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC.
+  Colorimeter application using the :adi:`AD7175-2` Sigma-Delta ADC.
 
 Additional Resources
 --------------------------------------------------------------------------------

docs/library/template_framework/interface.rst

@@ -19,7 +19,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml`
+   * - :git-hdl:`library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml`
      - Interface definition file
 
 Signal Pins

docs/library/template_framework/template_module.rst

@@ -17,9 +17,9 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution.v`
+   * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution.v`
      - Verilog source for the peripheral.
-   * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl`
+   * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl`
      - TCL script to generate the Vivado IP-integrator project for the peripheral.
 
 Configuration Parameters

docs/library/template_ip/index.rst

@@ -22,7 +22,7 @@ Files
 
    * - Name
      - Description
-   * - :git-hdl:`master:library/axi_dmac/axi_dmac.v`
+   * - :git-hdl:`library/axi_dmac/axi_dmac.v`
      - Verilog source for the peripheral.
 
 
@@ -108,12 +108,12 @@ from the interface module.
 Software Guidelines
 --------------------------------------------------------------------------------
 
-Linux is supported also using :git-linux:`/`.
+Linux is supported also using :git-linux:`master:/`.
 
 References
 --------------------------------------------------------------------------------
 
 * :git-hdl:`/`, :git-hdl:`library/axi_ad777x` library.
-* :git-linux:`/`.
+* :git-linux:`master:/`.
 * :xilinx:`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>`.
 * :xilinx:`Zynq-7000 SoC Packaging and Pinout <support/documentation/user_guides/ug865-Zynq-7000-Pkg-Pinout.pdf>`.

docs/projects/ad7616_sdz/index.rst

@@ -6,15 +6,15 @@ AD7616-SDZ HDL project
 Overview
 -------------------------------------------------------------------------------
 
-The :part:`AD7616` is a 16-bit, data acquisition system (DAS) that supports
+The :adi:`AD7616` is a 16-bit, data acquisition system (DAS) that supports
-dual simultaneous sampling of 16 channels. The :part:`AD7616` operates from a
+dual simultaneous sampling of 16 channels. The :adi:`AD7616` operates from a
 single 5 V supply and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar
 input signals while sampling at throughput rates up to 1 MSPS per channel pair
 with 90 dB SNR. Higher SNR performance can be achieved with the on-chip
 oversampling mode; 92 dB for an oversampling ratio of 2.
 
 The input clamp protection circuitry can tolerate voltages up to ±20 V.
-The :part:`AD7616` has 1 MΩ analog input impedance regardless of sampling
+The :adi:`AD7616` has 1 MΩ analog input impedance regardless of sampling
 frequency. The single supply operation, on-chip filtering, and high input
 impedance eliminate the need for driver op-amps and external bipolar supplies.
 
@@ -26,23 +26,23 @@ high-speed serial and parallel interfaces.
 Supported boards
 -------------------------------------------------------------------------------
 
--  :part:`EVAL-AD7616 <EVAL-AD7616>`
+-  :adi:`EVAL-AD7616 <EVAL-AD7616>`
 
 Supported devices
 -------------------------------------------------------------------------------
 
--  :part:`AD7616`
+-  :adi:`AD7616`
 
 Supported carriers
 -------------------------------------------------------------------------------
 
--  :xilinx:`ZedBoard` on FMC slot
+-  :xilinx:`ZedBoard <products/boards-and-kits/1-8dyf-11.html>` on FMC slot
 -  :xilinx:`ZC706` on FMC LPC slot
 
 Other required hardware
 -------------------------------------------------------------------------------
 
--   :part:`SDP-I-FMC <EVAL-SDP-I-FMC>`
+-   :adi:`SDP-I-FMC <EVAL-SDP-I-FMC>`
 
 Block design
 -------------------------------------------------------------------------------
@@ -117,31 +117,6 @@ LK40               A         Onboard 5v0 power supply selected
 LK41               A         Onboard 3v3 power supply selected
 ================== ========= ====================================
 
-IP list
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  :git-hdl:`AD_EDGE_DETECT <main:library/common/ad_edge_detect.v>`
--  :git-hdl:`AXI_AD7616 <main:library/axi_ad7616>` *
--  :git-hdl:`AXI_CLKGEN <main:library/axi_clkgen>`
--  :git-hdl:`AXI_DMAC <main:library/axi_dmac>`
--  :git-hdl:`AXI_HDMI_TX <main:library/axi_hdmi_tx>`
--  :git-hdl:`AXI_I2S_ADI <main:library/axi_i2s_adi>`
--  :git-hdl:`AXI_PWM_GEN <main:library/axi_pwm_gen>`
--  :git-hdl:`AXI_SPDIF_TX <main:library/axi_spdif_tx>`
--  :git-hdl:`AXI_SPI_ENGINE <main:library/spi_engine/axi_spi_engine>` **
--  :git-hdl:`AXI_SYSID <main:library/axi_sysid>`
--  :git-hdl:`SPI_ENGINE_EXECUTION <main:library/spi_engine/spi_engine_execution>` **
--  :git-hdl:`SPI_ENGINE_INTERCONNECT <main:library/spi_engine/spi_engine_interconnect>` **
--  :git-hdl:`SPI_ENGINE_OFFLOAD <main:library/spi_engine/spi_engine_offload>` **
--  :git-hdl:`SYNC_BITS <main:library/util_cdc/sync_bits.v>`
--  :git-hdl:`SYSID_ROM <main:library/sysid_rom>`
-
-.. admonition:: Legend
-   :class: note
-
-   -   ``*`` instantiated only for SER_PAR_N=0 (parallel interface)
-   -   ``**`` instantiated only for SER_PAR_N=1 (serial interface)
-
 CPU/Memory interconnects addresses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -277,7 +252,7 @@ Building the HDL project
 
 The design is built upon ADI's generic HDL reference design framework.
 ADI does not distribute the bit/elf files of these projects so they
-must be built from the sources available :git-hdl:`here <main:/>`. To get
+must be built from the sources available :git-hdl:`here </>`. To get
 the source you must
 `clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
 the HDL repository, and then build the project as follows:.
@@ -331,14 +306,14 @@ Systems related
 Hardware related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  Product datasheet: :part:`AD7616`
+-  Product datasheet: :adi:`AD7616`
 
 -  `UG-1012, Evaluation Board User Guide <https://www.analog.com/media/en/technical-documentation/user-guides/EVAL-AD7616SDZ-7616-PSDZ-UG-1012.pdf>`__
 
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`ad7616_sdz HDL project <main:projects/ad7616_sdz>`
+-  :git-hdl:`ad7616_sdz HDL project <projects/ad7616_sdz>`
 
 .. list-table::
    :widths: 30 35 35
@@ -348,53 +323,53 @@ HDL related
      - Source code link
      - Documentation link
    * - AD_EDGE_DETECT
-     - :git-hdl:`library/common/ad_edge_detect.v <main:library/common/ad_edge_detect.v>`
+     - :git-hdl:`library/common/ad_edge_detect.v`
      -
    * - AXI_AD7616
-     - :git-hdl:`library/axi_ad7616 <main:library/axi_ad7616>` *
+     - :git-hdl:`library/axi_ad7616` *
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_ad7616>`
    * - AXI_CLKGEN
-     - :git-hdl:`library/axi_dmac <main:library/axi_clkgen>`
+     - :git-hdl:`library/axi_clkgen`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_clkgen>`
    * - AXI_DMAC
-     - :git-hdl:`library/axi_dmac <master:library/axi_dmac>`
+     - :git-hdl:`library/axi_dmac`
      - :ref:`here <axi_dmac>`
    * - AXI_HDMI_TX
-     - :git-hdl:`library/axi_hdmi_tx <main:library/axi_hdmi_tx>`
+     - :git-hdl:`library/axi_hdmi_tx`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_hdmi_tx>`
    * - AXI_I2S_ADI
-     - :git-hdl:`library/axi_i2s_adi <main:library/axi_i2s_adi>`
+     - :git-hdl:`library/axi_i2s_adi`
      -
    * - AXI_PWM_GEN
-     - :git-hdl:`library/axi_pwm_gen <main:library/axi_pwm_gen>`
+     - :git-hdl:`library/axi_pwm_gen`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_pwm_gen>`
    * - AXI_SPDIF_TX
-     - :git-hdl:`library/axi_spdif_tx <main:library/axi_spdif_tx>`
+     - :git-hdl:`library/axi_spdif_tx`
      -
    * - AXI_SPI_ENGINE
-     - :git-hdl:`library/spi_engine/axi_spi_engine <main:library/spi_engine/axi_spi_engine>`  **
+     - :git-hdl:`library/spi_engine/axi_spi_engine`  **
      - :ref:`here <spi_engine axi>`
    * - AXI_SYSID
-     - :git-hdl:`library/axi_sysid <main:library/axi_sysid>`
+     - :git-hdl:`library/axi_sysid`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - AXI_SPI_ENGINE
-     - :git-hdl:`library/spi_engine/axi_spi_engine <main:library/spi_engine/axi_spi_engine>`  **
+     - :git-hdl:`library/spi_engine/axi_spi_engine`  **
      - :ref:`here <spi_engine axi>`
    * - SPI_ENGINE_EXECUTION
-     - :git-hdl:`library/spi_engine/spi_engine_execution <main:library/spi_engine/spi_engine_execution>` **
+     - :git-hdl:`library/spi_engine/spi_engine_execution` **
      - :ref:`here <spi_engine execution>`
    * - SPI_ENGINE_INTERCONNECT
-     - :git-hdl:`library/spi_engine/spi_engine_interconnect <main:library/spi_engine/spi_engine_interconnect>` **
+     - :git-hdl:`library/spi_engine/spi_engine_interconnect` **
      - :ref:`here <spi_engine interconnect>`
    * - SPI_ENGINE_OFFLOAD
-     - :git-hdl:`library/spi_engine/spi_engine_offload <main:library/spi_engine/spi_engine_offload>` **
+     - :git-hdl:`library/spi_engine/spi_engine_offload` **
      - :ref:`here <spi_engine offload>`
    * - SYNC_BITS
-     - :git-hdl:`library/util_cdc/sync_bits.v <main:library/util_cdc/sync_bits.v>`
+     - :git-hdl:`library/util_cdc/sync_bits.v`
      - 
    * - SYSID_ROM
-     - :git-hdl:`library/sysid_rom <main:library/sysid_rom>`
+     - :git-hdl:`library/sysid_rom`
-     -
+     - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
 
 .. admonition:: Legend
    :class: note

docs/projects/ad9081_fmca_ebz/index.rst

@@ -6,7 +6,7 @@ AD9081-FMCA-EBZ/AD9082-FMCA-EBZ HDL project
 Overview
 -------------------------------------------------------------------------------
 
-The :part:`AD9081-FMCA-EBZ <EVAL-AD9081>` / :part:`AD9082-FMCA-EBZ <EVAL-AD9082>`
+The :adi:`AD9081-FMCA-EBZ <EVAL-AD9081>` / :adi:`AD9082-FMCA-EBZ <EVAL-AD9082>`
 reference design (also known as Single MxFE) is a processor based
 (e.g. Microblaze) embedded system.
 The design consists from a receive and a transmit chain.
@@ -38,19 +38,19 @@ but must share the same reference clock.
 Supported boards
 -------------------------------------------------------------------------------
 
--  :part:`AD9081-FMCA-EBZ <EVAL-AD9081>`
+-  :adi:`AD9081-FMCA-EBZ <EVAL-AD9081>`
--  :part:`AD9082-FMCA-EBZ <EVAL-AD9082>`
+-  :adi:`AD9082-FMCA-EBZ <EVAL-AD9082>`
 
 Supported devices
 -------------------------------------------------------------------------------
 
--  :part:`AD9081`
+-  :adi:`AD9081`
--  :part:`AD9082`
+-  :adi:`AD9082`
--  :part:`AD9177`
+-  :adi:`AD9177`
--  :part:`AD9207`
+-  :adi:`AD9207`
--  :part:`AD9209`
+-  :adi:`AD9209`
--  :part:`AD9986`
+-  :adi:`AD9986`
--  :part:`AD9988`
+-  :adi:`AD9988`
 
 Supported carriers
 -------------------------------------------------------------------------------
@@ -62,7 +62,7 @@ Supported carriers
    * - Evaluation board
      - Carrier
      - FMC slot
-   * - :part:`AD9081-FMCA-EBZ <EVAL-AD9081>`
+   * - :adi:`AD9081-FMCA-EBZ <EVAL-AD9081>`
      - `A10SoC`_
      - FMCA
    * -
@@ -88,7 +88,7 @@ Supported carriers
    * - Evaluation board
      - Carrier
      - FMC slot
-   * - :part:`AD9082-FMCA-EBZ <EVAL-AD9082>`
+   * - :adi:`AD9082-FMCA-EBZ <EVAL-AD9082>`
      - :xilinx:`VCK190`
      - FMC0
    * -
@@ -445,12 +445,12 @@ Building the HDL project
 
 The design is built upon ADI's generic HDL reference design framework.
 ADI does not distribute the bit/elf files of these projects so they
-must be built from the sources available :git-hdl:`here <master:/>`. To get
+must be built from the sources available :git-hdl:`here </>`. To get
 the source you must
 `clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
 the HDL repository.
 
-Then go to the :git-hdl:`projects/ad9081_fmca_ebz <master:projects/ad9081_fmca_ebz>`
+Then go to the :git-hdl:`projects/ad9081_fmca_ebz <projects/ad9081_fmca_ebz>`
 location and run the make command by typing in your command prompt:
 
 **Linux/Cygwin/WSL**
@@ -692,18 +692,18 @@ Hardware related
 
 -  Product datasheets:
 
-   -  :part:`AD9081`
+   -  :adi:`AD9081`
-   -  :part:`AD9082`
+   -  :adi:`AD9082`
-   -  :part:`AD9988`
+   -  :adi:`AD9988`
-   -  :part:`AD9986`
+   -  :adi:`AD9986`
 -  `UG-1578, Device User Guide <https://www.analog.com/media/en/technical-documentation/user-guides/ad9081-ad9082-ug-1578.pdf>`__
 -  `UG-1829, Evaluation Board User Guide <https://www.analog.com/media/en/technical-documentation/user-guides/ad9081-fmca-ebz-9082-fmca-ebz-ug-1829.pdf>`__
 
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`AD9081_FMCA_EBZ HDL project source code <master:projects/ad9081_fmca_ebz>`
+-  :git-hdl:`AD9081_FMCA_EBZ HDL project source code <projects/ad9081_fmca_ebz>`
--  :git-hdl:`AD9082_FMCA_EBZ HDL project source code <master:projects/ad9082_fmca_ebz>`
+-  :git-hdl:`AD9082_FMCA_EBZ HDL project source code <projects/ad9082_fmca_ebz>`
 
 .. list-table::
    :widths: 30 35 35
@@ -713,40 +713,40 @@ HDL related
      - Source code link
      - Documentation link
    * - AXI_DMAC
-     - :git-hdl:`library/axi_dmac <master:library/axi_dmac>`
+     - :git-hdl:`library/axi_dmac`
      - :ref:`here <axi_dmac>`
    * - AXI_SYSID
-     - :git-hdl:`library/axi_sysid <master:library/axi_sysid>`
+     - :git-hdl:`library/axi_sysid`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - SYSID_ROM
-     - :git-hdl:`library/sysid_rom <master:library/sysid_rom>`
+     - :git-hdl:`library/sysid_rom`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - UTIL_CPACK2
-     - :git-hdl:`library/util_pack/util_cpack2 <master:library/util_pack/util_cpack2>`
+     - :git-hdl:`library/util_pack/util_cpack2`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/util_cpack>`
    * - UTIL_UPACK2
-     - :git-hdl:`library/util_pack/util_upack2 <master:library/util_pack/util_upack2>`
+     - :git-hdl:`library/util_pack/util_upack2`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/util_upack>`
    * - UTIL_ADXCVR for AMD
-     -  :git-hdl:`library/xilinx/util_adxcvr <master:library/xilinx/util_adxcvr>`
+     -  :git-hdl:`library/xilinx/util_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/util_xcvr>`
    * - AXI_ADXCVR for Intel
-     -  :git-hdl:`library/intel/axi_adxcvr <master:library/intel/axi_adxcvr>`
+     -  :git-hdl:`library/intel/axi_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/axi_adxcvr>`
    * - AXI_ADXCVR for AMD
-     -  :git-hdl:`library/intel/axi_adxcvr <master:library/xilinx/axi_adxcvr>`
+     -  :git-hdl:`library/xilinx/axi_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/axi_adxcvr>`
    * - AXI_JESD204_RX
-     -  :git-hdl:`library/jesd204/axi_jesd204_rx <master:library/jesd204/axi_jesd204_rx>`
+     -  :git-hdl:`library/jesd204/axi_jesd204_rx`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/axi_jesd204_rx>`
    * - AXI_JESD204_TX
-     -  :git-hdl:`library/jesd204/axi_jesd204_tx <master:library/jesd204/axi_jesd204_tx>`
+     -  :git-hdl:`library/jesd204/axi_jesd204_tx`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/axi_jesd204_tx>`
    * - JESD204_TPL_ADC
-     -  :git-hdl:`library/jesd204/jesd204_tpl_adc <master:library/jesd204/jesd204_tpl_adc>`
+     -  :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_adc`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/jesd204_tpl_adc>`
    * - JESD204_TPL_DAC
-     -  :git-hdl:`library/jesd204/jesd204_tpl_dac <master:library/jesd204/jesd204_tpl_dac>`
+     -  :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/jesd204_tpl_dac>`
 
 -  :dokuwiki:`[Wiki] Generic JESD204B block designs <resources/fpga/docs/hdl/generic_jesd_bds>`

docs/projects/ad9783_ebz/index.rst

@@ -6,7 +6,7 @@ AD9783-EBZ HDL project
 Overview
 -------------------------------------------------------------------------------
 
-The :part:`AD9783` includes pin-compatible, high dynamic range, dual
+The :adi:`AD9783` includes pin-compatible, high dynamic range, dual
 digital-to-analog converters (DACs) with 16-bit resolution, and sample rates of
 up to 500 MSPS.
 
@@ -14,20 +14,20 @@ The device includes specific features for direct conversion transmit
 applications, including gain and offset compensation, interfacing seamlessly
 with analog quadrature modulators.
 
-The :part:`EVAL-AD9783` board is connected to the FPGA carrier through
+The :adi:`EVAL-AD9783` board is connected to the FPGA carrier through
-:part:`AD-DAC-FMC`-ADP interposer board.
+:adi:`AD-DAC-FMC`-ADP interposer board.
 
 Supported boards
 -------------------------------------------------------------------------------
 
--  :part:`EVAL-AD9783`
+-  :adi:`EVAL-AD9783`
 
 Supported devices
 -------------------------------------------------------------------------------
 
--  :part:`AD9780`
+-  :adi:`AD9780`
--  :part:`AD9781`
+-  :adi:`AD9781`
--  :part:`AD9783`
+-  :adi:`AD9783`
 
 Supported carriers
 -------------------------------------------------------------------------------
@@ -53,7 +53,7 @@ Clock scheme
 -  External clock source connected to J1 (CLOCK IN)
 -  For maximum performance, give a 500 MHz clock
 
-To make the connection between the :part:`EVAL-AD9783` evaluation board and
+To make the connection between the :adi:`EVAL-AD9783` evaluation board and
 the carrier using SPI, some hardware changes must be done to the evaluation
 board. These are presented in detail in the **Connections and hardware changes**
 section.
@@ -107,7 +107,7 @@ Building the HDL project
 
 The design is built upon ADI's generic HDL reference design framework.
 ADI does not distribute the bit/elf files of these projects so they
-must be built from the sources available :git-hdl:`here <master:/>`. To get
+must be built from the sources available :git-hdl:`here </>`. To get
 the source you must
 `clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
 the HDL repository, and then build the project as follows:
@@ -159,16 +159,16 @@ Hardware related
 
 -  Product datasheets:
 
-   -  :part:`AD9780`
+   -  :adi:`AD9780`
-   -  :part:`AD9781`
+   -  :adi:`AD9781`
-   -  :part:`AD9783`
+   -  :adi:`AD9783`
-   -  :part:`EVAL-AD9783`
+   -  :adi:`EVAL-AD9783`
-   -  :part:`AD-DAC-FMC`-ADP
+   -  :adi:`AD-DAC-FMC`-ADP
 
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`AD9783_EBZ HDL project source code <master:projects/ad9783_ebz>`
+-  :git-hdl:`AD9783_EBZ HDL project source code <projects/ad9783_ebz>`
 
 .. list-table::
    :widths: 30 35 35
@@ -178,19 +178,19 @@ HDL related
      - Source code link
      - Documentation link
    * - AXI_AD9783
-     - :git-hdl:`library/axi_ad9783 <master:library/axi_ad9783>`
+     - :git-hdl:`library/axi_ad9783`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_ad9783>`
    * - AXI_DMAC
-     - :git-hdl:`library/axi_dmac <master:library/axi_dmac>`
+     - :git-hdl:`library/axi_dmac`
      - :ref:`here <axi_dmac>`
    * - AXI_SYSID
-     - :git-hdl:`library/axi_sysid <master:library/axi_sysid>`
+     - :git-hdl:`library/axi_sysid`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - SYSID_ROM
-     - :git-hdl:`library/sysid_rom <master:library/sysid_rom>`
+     - :git-hdl:`library/sysid_rom`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - UTIL_UPACK2
-     - :git-hdl:`library/util_pack/util_upack2 <master:library/util_pack/util_upack2>`
+     - :git-hdl:`library/util_pack/util_upack2`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/util_upack>`
 
 Software related

docs/projects/common/support.rst

@@ -2,7 +2,7 @@ Support
 -------------------------------------------------------------------------------
 
 `Analog Devices, Inc.`_ will provide **limited** online support for anyone using
-the :git-hdl:`reference design <master:/>` with `ADI`_ components
+the :git-hdl:`reference design <>` with `ADI`_ components
 via the :ez:`fpga` FPGA reference designs forum.
 
 For questions regarding the `ADI`_ Linux device drivers, device trees, etc. from
@@ -10,7 +10,7 @@ our :git-linux:`Linux GitHub repository <master:/>`, the team will offer
 support on the :ez:`linux-software-drivers` Linux software drivers forum.
 
 For questions concerning the `ADI`_ No-OS drivers, from our
-:git-no-os:`No-OS GitHub repository <master:/>`, the team will offer support
+:git-no-os:`No-OS GitHub repository <main:/>`, the team will offer support
 on the :ez:`microcontroller-no-os-drivers` microcontroller No-OS drivers forum.
 
 It should be noted, that the older the tools' versions and release

docs/projects/template/index.rst

@@ -17,17 +17,17 @@ Supported boards
 
 **\*IF IT APPLIES**\ \*
 
--  :part:`AD9081-FMCA-EBZ <EVAL-AD9081>`
+-  :adi:`AD9081-FMCA-EBZ <EVAL-AD9081>`
--  :part:`AD9082-FMCA-EBZ <EVAL-AD9082>`
+-  :adi:`AD9082-FMCA-EBZ <EVAL-AD9082>`
 
 Supported devices
 -------------------------------------------------------------------------------
 
 **\*EXAMPLES**\ \*
 
--  :part:`AD9081`
+-  :adi:`AD9081`
--  :part:`AD9177`
+-  :adi:`AD9177`
--  :part:`AD9209`
+-  :adi:`AD9209`
 
 Supported carriers
 -------------------------------------------------------------------------------
@@ -42,7 +42,7 @@ another carrier. Take these tables as an example:**\ \*
    * - Evaluation board
      - Carrier
      - FMC slot
-   * - :part:`AD9081-FMCA-EBZ <EVAL-AD9081>`
+   * - :adi:`AD9081-FMCA-EBZ <EVAL-AD9081>`
      - `A10SoC`_
      - FMCA
    * -
@@ -68,7 +68,7 @@ another carrier. Take these tables as an example:**\ \*
    * - Evaluation board
      - Carrier
      - FMC slot
-   * - :part:`AD9082-FMCA-EBZ <EVAL-AD9082>`
+   * - :adi:`AD9082-FMCA-EBZ <EVAL-AD9082>`
      - :xilinx:`VCK190`
      - FMC0
    * -
@@ -445,7 +445,7 @@ Building the HDL project
 
 The design is built upon ADI's generic HDL reference design framework.
 ADI does not distribute the bit/elf files of these projects so they
-must be built from the sources available :git-hdl:`here <master:/>`. To get
+must be built from the sources available :git-hdl:`here <>`. To get
 the source you must
 `clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
 the HDL repository.
@@ -635,10 +635,10 @@ Hardware related
 
 -  Product datasheets:
 
-   -  :part:`AD9081`
+   -  :adi:`AD9081`
-   -  :part:`AD9082`
+   -  :adi:`AD9082`
-   -  :part:`AD9988`
+   -  :adi:`AD9988`
-   -  :part:`AD9986`
+   -  :adi:`AD9986`
 -  `UG-1578, Device User Guide <https://www.analog.com/media/en/technical-documentation/user-guides/ad9081-ad9082-ug-1578.pdf>`__
 -  `UG-1829, Evaluation Board User Guide <https://www.analog.com/media/en/technical-documentation/user-guides/ad9081-fmca-ebz-9082-fmca-ebz-ug-1829.pdf>`__
 
@@ -655,8 +655,8 @@ HDL related
 
 **THIS IS JUST AN EXAMPLE**
 
--  :git-hdl:`AD9081_FMCA_EBZ HDL project source code <master:projects/ad9081_fmca_ebz>`
+-  :git-hdl:`AD9081_FMCA_EBZ HDL project source code <projects/ad9081_fmca_ebz>`
--  :git-hdl:`AD9082_FMCA_EBZ HDL project source code <master:projects/ad9082_fmca_ebz>`
+-  :git-hdl:`AD9082_FMCA_EBZ HDL project source code <projects/ad9082_fmca_ebz>`
 
 .. list-table::
    :widths: 30 35 35
@@ -666,40 +666,40 @@ HDL related
      - Source code link
      - Documentation link
    * - AXI_DMAC
-     - :git-hdl:`library/axi_dmac <master:library/axi_dmac>`
+     - :git-hdl:`library/axi_dmac`
      - :ref:`here <axi_dmac>`
    * - AXI_SYSID
-     - :git-hdl:`library/axi_sysid <master:library/axi_sysid>`
+     - :git-hdl:`library/axi_sysid`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - SYSID_ROM
-     - :git-hdl:`library/sysid_rom <master:library/sysid_rom>`
+     - :git-hdl:`library/sysid_rom`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - UTIL_CPACK2
-     - :git-hdl:`library/util_pack/util_cpack2 <master:library/util_pack/util_cpack2>`
+     - :git-hdl:`library/util_pack/util_cpack2`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/util_cpack>`
    * - UTIL_UPACK2
-     - :git-hdl:`library/util_pack/util_upack2 <master:library/util_pack/util_upack2>`
+     - :git-hdl:`library/util_pack/util_upack2`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/util_upack>`
    * - UTIL_ADXCVR for AMD
-     -  :git-hdl:`library/xilinx/util_adxcvr <master:library/xilinx/util_adxcvr>`
+     -  :git-hdl:`library/xilinx/util_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/util_xcvr>`
    * - AXI_ADXCVR for Intel
-     -  :git-hdl:`library/intel/axi_adxcvr <master:library/intel/axi_adxcvr>`
+     -  :git-hdl:`library/intel/axi_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/axi_adxcvr>`
    * - AXI_ADXCVR for AMD
-     -  :git-hdl:`library/intel/axi_adxcvr <master:library/xilinx/axi_adxcvr>`
+     -  :git-hdl:`library/xilinx/axi_adxcvr`
      -  :dokuwiki:`[Wiki] <resources/fpga/docs/axi_adxcvr>`
    * - AXI_JESD204_RX
-     -  :git-hdl:`library/jesd204/axi_jesd204_rx <master:library/jesd204/axi_jesd204_rx>`
+     -  :git-hdl:`library/jesd204/axi_jesd204_rx`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/axi_jesd204_rx>`
    * - AXI_JESD204_TX
-     -  :git-hdl:`library/jesd204/axi_jesd204_tx <master:library/jesd204/axi_jesd204_tx>`
+     -  :git-hdl:`library/jesd204/axi_jesd204_tx`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/axi_jesd204_tx>`
    * - JESD204_TPL_ADC
-     -  :git-hdl:`library/jesd204/jesd204_tpl_adc <master:library/jesd204/jesd204_tpl_adc>`
+     -  :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_adc`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/jesd204_tpl_adc>`
    * - JESD204_TPL_DAC
-     -  :git-hdl:`library/jesd204/jesd204_tpl_dac <master:library/jesd204/jesd204_tpl_dac>`
+     -  :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac`
      -  :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/jesd204_tpl_dac>`
 
 -  :dokuwiki:`[Wiki] Generic JESD204B block designs <resources/fpga/docs/hdl/generic_jesd_bds>`

docs/regmap/adi_regmap_common.txt

@@ -169,8 +169,8 @@ REG
 0x0007
 REG_FPGA_INFO
 FPGA device information
-:git-hdl:`master:library/scripts/adi_intel_device_info_enc.tcl` (Intel encoded values)
+:git-hdl:`library/scripts/adi_intel_device_info_enc.tcl` (Intel encoded values)
-:git-hdl:`master:library/scripts/adi_xilinx_device_info_enc.tcl` (Xilinx encoded values)
+:git-hdl:`library/scripts/adi_xilinx_device_info_enc.tcl` (Xilinx encoded values)
 ENDREG
 
 FIELD

docs/regmap/adi_regmap_dmac.txt

@@ -330,7 +330,7 @@ X_LENGTH
 ENDREG
 
 FIELD
-[23:0] {log2(max(\n''DMA_DATA_WIDTH_SRC'',\n''DMA_DATA_WIDTH_DEST''\n)/8){1'b1}}
+[23:0] {log2(max(''DMA_DATA_WIDTH_SRC'', ''DMA_DATA_WIDTH_DEST'')/8){1'b1}}
 X_LENGTH
 RW
 Number of bytes to transfer - 1.

docs/requirements.txt

@@ -2,6 +2,8 @@ sphinx
 lxml
 furo
 wavedrom
+aiohttp
+aiodns
 sphinxcontrib-wavedrom
 sphinxcontrib-svg2pdfconverter
 https://github.com/hdl/pyhdlparser/tarball/master

docs/sources/custom.css

@@ -60,7 +60,10 @@ table.regmap {
 table.regmap .caption-text{
 	font-size: 1rem;
 }
-th, td.type, td.default {
+td {
+	min-width: 4em;
+}
+th, td.type {
 	white-space: nowrap;
 }
 td.description {
@@ -130,11 +133,18 @@ td.description {
 	transform: rotate(45deg);
 	margin-top: -.5em;
 }
+.collapsible_content {
+	overflow: auto;
+}
 .collapsible_input:checked ~ .collapsible_content {
 	height: 100%;
 	opacity: 1;
 }
 .default {
-	min-width: 7em;
+	min-width: 5em;
+	max-width: 11em;
 	line-break: anywhere;
 }
+.default .pre {
+	white-space: pre;
+}

docs/user_guide/architecture.rst

@@ -15,7 +15,7 @@ subsystems:
       dependent**
    -  it describes part of the ``system_wrapper`` module
    -  located in
-      :git-hdl:`projects/common <master:projects/common>`;
+      :git-hdl:`projects/common <projects/common>`;
       one for each carrier
 
 -  **Board design** --- description of what the **board** attached to
@@ -147,7 +147,7 @@ CPU/Memory interconnects addresses
 The memory addresses that will be used by software are based on the HDL
 addresses of the IP register map, to which an offset is added, depending
 on the architecture of the used FPGA (see also :git-hdl:`ad_cpu_interconnect
-procedure <master:projects/scripts/adi_board.tcl>`; architecture is
+procedure <projects/scripts/adi_board.tcl>`; architecture is
 specified by ``sys_zynq`` variable, for AMD FPGAs).
 
 **Zynq-7000 and 7 Series**
@@ -200,7 +200,7 @@ HDMI
 
 There is HDMI support for all the carriers which are using the ADV7511
 as HDMI transmitter. The HDMI transmitter core can be found
-`here <https://github.com/analogdevicesinc/hdl/tree/master/library/axi_hdmi_tx>`__.
+:git-hdl:`here <library/axi_hdmi_tx>`.
 
 GPIOs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/user_guide/build_hdl.rst

@@ -34,10 +34,10 @@ HDL project from the repository:
 #. The proper Vivado/Quartus version can be found in:
 
    -  Starting with ``hdl_2021_r1`` release branch:
-      :git-hdl:`master:scripts/adi_env.tcl`
+      :git-hdl:`scripts/adi_env.tcl`
    -  For ``hdl_2019_r2`` and older:
-      :git-hdl:`hdl/projects/scripts/adi_project_xilinx.tcl <master:projects/scripts/adi_project_xilinx.tcl>` for Vivado, and
+      :git-hdl:`hdl/projects/scripts/adi_project_xilinx.tcl <projects/scripts/adi_project_xilinx.tcl>` for Vivado, and
-      :git-hdl:`hdl/projects/scripts/adi_project_intel.tcl <master:projects/scripts/adi_project_intel.tcl>` for Quartus.
+      :git-hdl:`hdl/projects/scripts/adi_project_intel.tcl <projects/scripts/adi_project_intel.tcl>` for Quartus.
 
 #. Download the tools from the following links:
 
@@ -100,7 +100,7 @@ Setup the HDL repository
 
 These designs are built upon ADI's generic HDL reference designs framework.
 ADI does not distribute the bit/elf files of these projects so they
-must be built from the sources available :git-hdl:`here <master:/>`. To get
+must be built from the sources available :git-hdl:`here </>`. To get
 the source you must
 `clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
 the HDL repository.
@@ -126,8 +126,8 @@ to the :ref:`git_repository` section for more details.
    performance, you must clone your hdl repository in the WSL file system.
    For example: (:code:`\\\\wsl.localhost\\Ubuntu\\home\\username\\hdl`)
 
-The above command clones the 'default' branch, which is the 'master' for
+The above command clones the 'default' branch, which is the 'main' for
-HDL. The 'master' branch always points to the latest stable release
+HDL. The 'main' branch always points to the latest stable release
 branch, but it also has features **that are not fully tested**. If you
 want to switch to any other branch you need to checkout that branch:
 

docs/user_guide/docs_guidelines.rst

@@ -17,7 +17,7 @@ Templates are available:
 
 * :git-hdl:`docs/library/template_ip` (:ref:`rendered <template_ip>`).
 * :git-hdl:`docs/library/template_framework` (:ref:`rendered <template_framework>`).
-* :git-hdl:`docs/projects/template_project` (:ref:`rendered <template_project>`).
+* :git-hdl:`docs/projects/template` (:ref:`rendered <template_project>`).
 
 Remove the ``:orphan:`` in the first line, it is to hide the templates from the
 `TOC tree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_.
@@ -151,13 +151,12 @@ it is not recommended.
 Third-party directives and roles
 --------------------------------------------------------------------------------
 
-Third-party tools are used to expand Sphinx functionality, for example, to
+Third-party tools are used to expand Sphinx functionality, if you haven't already,
-generate component diagrams.
+do:
 
-.. tip::
+.. code:: bash
 
-   Check :git-hdl:`docs/Containterfile` for a recipe to install these
+   pip install -r requirements.txt
-   tools, either in the host or in a container.
 
 Symbolator directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -183,37 +182,53 @@ Color role
 
 To print text in red or green, use :code:`:red:\`text\`` and :code:`:green:\`text\``.
 
-Git role
+Link roles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+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 role
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
 The Git role allows to create links to the Git repository with a shorter syntax.
 The role syntax is :code:`:git-repo:\`text <branch:path>\``, for example:
 
-* :code:`:git-hdl:\`master:docs/contributing/guidelines.rst\``
+* :code:`:git-hdl:\`main:docs/user_guide/docs_guidelines.rst\``
-  renders as :git-hdl:`master:docs/contributing/guidelines.rst`.
+  renders as :git-hdl:`main:docs/user_guide/docs_guidelines.rst`.
-* :code:`:git-hdl:\`Guidelines <docs/contributing/guidelines.rst>\``
+* :code:`:git-hdl:\`Guidelines <docs/user_guide/docs_guidelines.rst>\``
-  renders as :git-hdl:`Guidelines <docs/contributing/guidelines.rst>`.
+  renders as :git-hdl:`Guidelines <docs/user_guide/docs_guidelines.rst>`.
 
-The branch field is optional and will be filled with the current branch.
+When the branch field is not present, it will be filled with the current branch.
-The text field is optional and will be filled with the file or directory name.
+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.
+
+The text field is optional and will be filled with the full path.
 
 Finally, you can do :code:`:git-repo:\`/\`` for a link to the root of the
 repository with pretty naming, for example, :code:`:git-hdl:\`/\`` is rendered
 as :git-hdl:`/`.
 
-Part role
+ADI role
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-The part role creates links for a part to the Analog Devices Inc. website.
+The adi role creates links for a webpage to the Analog Devices Inc. website.
 
-The role syntax is :code:`:part:\`text <part_id>\``, for example,
+The role syntax is :code:`:adi:\`text <webpage>\``, for example,
-:code:`:part:\`AD7175-2 <ad7175-2>\``.
+:code:`:adi:\`AD7175-2 <ad7175-2>\``.
 Since links are case insensitive, you can also reduce it to
-:code:`:part:\`AD7175-2\``, when *part_id* is the same as *text* and will render
+:code:`:adi:\`AD7175-2\``, when *webpage* is the same as *text* and will render
-as :part:`AD7175-2`.
+as :adi:`AD7175-2`.
 
 Datasheet role
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 The datasheet role creates links for a datasheet in the Analog Devices Inc. website.
 
@@ -230,7 +245,7 @@ by just copying the link in the table of contents.
    figure number!
 
 Dokuwiki role
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 The dokuwiki role creates links to the Analog Devices Inc. wiki website.
 The role syntax is :code:`:dokuwiki:\`text <path>\``, for example,
@@ -239,7 +254,7 @@ gets rendered as
 :dokuwiki:`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>`.
 
 EngineerZone role
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 The ez role creates links to the Analog Devices Inc. EngineerZone support website.
 The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\``
@@ -250,7 +265,7 @@ For Linux Software Drivers, it is :code:`:ez:\`linux-software-drivers\``.
 For Microcontroller no-OS Drivers it is :code:`:ez:\`microcontroller-no-os-drivers\``.
 
 Vendor role
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 The vendor role creates links to the vendor's website.
 The role syntax is :code:`:vendor:\`text <path>\``, for example,
@@ -265,18 +280,19 @@ gets rendered
 :intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html`
 (not very readable).
 
-Supported vendors are: `xilinx` and `intel`.
+Supported vendors are: ``xilinx`` (AMD Xilinx), ``intel`` (Intel Altera) and
+``mw`` (MathWorks).
 
 HDL parameters directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The HDL parameters directive gets information parsed from *component.xml* library
+The HDL parameters directive gets information parsed from IP-XACT (*component.xml*)
-and generates a table with the IP parameters.
+library and generates a table with the IP parameters.
 
 .. note::
 
-   The *component.xml* files are generated by Vivado during the library build
+   The IP-XACT files are generated by Vivado during the library build and not by
-   and not by the documentation tooling.
+   the documentation tooling.
 
 The directive syntax is:
 
@@ -425,8 +441,12 @@ Notice how you can use any Sphinx syntax, even nest other directives.
 Global options for HDL directives
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use the `hide_collapsible_content` to set the default state of the collapsibles,
+Set ``hide_collapsible_content`` to True to hide the collapsibles by default.
-if you set to False, they be expanded by default.
+
+Set ``validate_links`` to True 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.
 
 Common sections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/user_guide/git_repository.rst

@@ -162,7 +162,7 @@ Repository releases and branches
 -------------------------------------------------------------------------------
 
 The repository may contain multiple branches and tags. The
-:git-hdl:`master <master:>` branch
+:git-hdl:`main </>` branch
 is the development branch (latest sources, but not stable). If you check
 out this branch, some builds may fail. If you are not into any kind of
 experimentation, you should only check out one of the release branch.
@@ -173,7 +173,7 @@ All our release branches have the following naming convention:
 
 ADI does two releases each year when all the projects get an update to
 support the latest tools and get additional new features. \*\* The
-master branch is always synchronized with the latest release.*\* If you
+main branch is always synchronized with the latest release.*\* If you
 are in doubt, ask us on :ez:`fpga`.
 
 .. note::
@@ -183,7 +183,7 @@ are in doubt, ask us on :ez:`fpga`.
 
    https://github.com/analogdevicesinc/hdl/releases
 
-   The latest version of tools used on master can be found at:
+   The latest version of tools used on main can be found at:
-   :git-hdl:`master:scripts/adi_env.tcl` (*required_vivado_version* and
+   :git-hdl:`scripts/adi_env.tcl` (*required_vivado_version* and
    *required_quartus_version* variables). For Intel Quartus Standard, the version
    is specified in each project that uses it, depending on the carrier.

docs/user_guide/hdl_coding_guideline.rst

@@ -316,7 +316,7 @@ to the last parenthesis of the last port.
 
 **A10.3**
 
-Commented parts of code **must** not be added to the master
+Commented parts of code **must** not be added to the main
 branch (i.e if, case, module instances, etc).
 
 **A11**

docs/user_guide/introduction.rst

@@ -7,10 +7,10 @@ The main purpose of this user guide is to help the user understand and use
 (modify or otherwise) the HDL resources provided by `Analog Devices, Inc.`_,
 and to provide advices and instructions for using these resources.
 These resources are found on the GitHub, the
-:git-hdl:`HDL repository <master:/>`.
+:git-hdl:`/`.
 
 After reading this guide, the user should be able to build a specific project
-from the :git-hdl:`HDL repository <master:/>` and be able to modify
+from the :git-hdl:`/` and be able to modify
 (if so desire) the digital data path implemented in the FPGA.
 Furthermore, all ADI developed and supported IPs are presented in detail.
 

docs/user_guide/porting_project.rst

@@ -83,7 +83,7 @@ components of it. The user should look at it as a suggestion only.
 
 .. tip::
 
-   In :git-hdl:`projects/common <master:projects/common>`/<carrier_name>
+   In :git-hdl:`projects/common <projects/common>`/<carrier_name>
    you can find templates for the *system_top.v*, *Makefile*, etc. to help you
    when creating a new project.
 

docs/user_guide/releases.rst

@@ -66,7 +66,7 @@ Release branches
      - AMD Xilinx
      - Release notes
      - List of supported projects and IP cores
-   * - :git-hdl:`master`
+   * - :git-hdl:`main <main:/>`
      - Quartus Pro 23.2
      - Vivado 2023.1
      -
@@ -145,13 +145,13 @@ When Intel or AMD have a new release, we usually follow them and update our
 tools in a timely manner.
 
 Changing the version of tool used on a branch is done by updating the
-git-hdl:`adi_env.tcl <master:scripts/adi_env.tcl>` script.
+git-hdl:`adi_env.tcl <scripts/adi_env.tcl>` script.
 
 If the tool version is not the one you want to use, keep in mind that when
 making a setup, you will have to build the software files with the same
 version, otherwise you might encounter problems in your setup.
 
-For example, you want to use an older version of Vivado on the master branch
+For example, you want to use an older version of Vivado on the main branch
 which uses a newer one. Then you will need to manually build the software
-files from the master branch, with the same version of Vitis too. Or for
+files from the main branch, with the same version of Vitis too. Or for
 Linux, to use the proper version of CROSS_COMPILE, etc.