Add documentation support

.github/workflows/top-level.yml

@@ -0,0 +1,92 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-doc:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - uses: actions/checkout@v4
+      with:
+        lfs: 'true'
+
+    - name: Install pip packages
+      working-directory: docs
+      run: |
+        pip install pip --upgrade
+        pip install -r requirements.txt --upgrade
+
+    - name: Build doc
+      working-directory: docs
+      run: |
+        make html
+
+    - name: Store the generated doc
+      uses: actions/upload-artifact@v4
+      with:
+        name: html
+        path: docs/_build/html
+
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [build-doc]
+    permissions:
+      contents: write
+
+    steps:
+    - run: |
+        git config --global user.name "${{ github.event.head_commit.committer.name }}"
+        git config --global user.email "${{ github.event.head_commit.committer.email }}"
+
+    - uses: actions/checkout@v4
+    - name: Create gh-pages branch
+      run: >
+        git ls-remote --exit-code --heads origin refs/heads/gh-pages ||
+        (
+          git reset --hard ;
+          git clean -fdx ;
+          git checkout --orphan gh-pages ;
+          git reset --hard;
+          git commit -m "empty" --allow-empty ;
+          git push origin gh-pages:gh-pages
+        )
+
+    - uses: actions/checkout@v4
+      with:
+        ref: 'gh-pages'
+        lfs: 'false'
+
+    - name: Empty gh-pages
+      run: |
+        git rm -r . --quiet || true
+
+    - uses: actions/download-artifact@v4
+      with:
+        name: html
+
+    - name: Patch doc build
+      run: |
+        rm -r _sources
+        touch .nojekyll
+
+    - name: Commit gh-pages
+      run: |
+        author=$(git log -1 --pretty=format:'%an')
+        email=$(git log -1 --pretty=format:'%ae')
+        commit=$(git rev-parse --short HEAD)
+
+        git add . >> /dev/null
+        git commit -m "deploy: ${GITHUB_SHA}" --allow-empty
+
+    - name: Push to gh-pages
+      run: >-
+        git push origin gh-pages:gh-pages

docs/Makefile

@@ -0,0 +1,13 @@
+SHELL         = /bin/bash
+SPHINXOPTS   ?=
+SPHINXBUILD  ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,42 @@
+# -- Project information ------------------------------------------------------
+
+repository = 'hdl'
+project = 'Testbenches'
+copyright = '2024, Analog Devices, Inc.'
+author = 'Analog Devices, Inc.'
+
+# -- General configuration ----------------------------------------------------
+
+extensions = [
+    "sphinx.ext.todo",
+    "sphinxcontrib.wavedrom",
+    "adi_doctools"
+]
+
+needs_extensions = {
+    'adi_doctools': '0.3'
+}
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+source_suffix = '.rst'
+
+# -- External docs configuration ----------------------------------------------
+
+interref_repos = ['doctools', 'hdl']
+
+# -- Custom extensions configuration ------------------------------------------
+
+hide_collapsible_content = True
+validate_links = False
+
+# -- todo configuration -------------------------------------------------------
+
+todo_include_todos = True
+todo_emit_warnings = True
+
+# -- Options for HTML output --------------------------------------------------
+
+html_theme = 'cosmic'
+html_static_path = ['sources']
+html_css_files = ["custom.css"]
+html_favicon = "sources/icon.svg"

docs/index.rst

@@ -0,0 +1,27 @@
+HDL Testbenches
+===============================================================================
+
+.. attention::
+
+   Work-in-progress, not all content has been imported yet.
+
+.. image:: sources/HDL_logo.svg
+   :align: center
+   :scale: 100%
+
+`Analog Devices Inc. <https://www.analog.com>`_
+HDL testbenches for various reference design and prototyping systems.
+This repository contains HDL code (SystemVerilog) and the required Tcl scripts
+to create and build a specific FPGA testbench example design using Xilinx toolchain.
+
+.. hdl-build-status::
+
+Contents
+===============================================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   user_guide/index
+   library/index
+   projects/index

docs/library/adi_vip/adi_vip_template/index.rst

@@ -0,0 +1,33 @@
+.. _adi_vip_template:
+
+ADI VIPs
+================================================================================
+
+Description
+
+Features
+--------------------------------------------------------------------------------
+
+Files
+--------------------------------------------------------------------------------
+
+VIP interface
+
+Configuration parameters
+--------------------------------------------------------------------------------
+
+Interface
+--------------------------------------------------------------------------------
+
+Functions
+--------------------------------------------------------------------------------
+
+Known Issues
+--------------------------------------------------------------------------------
+
+Technical Support
+--------------------------------------------------------------------------------
+
+References
+--------------------------------------------------------------------------------
+

docs/library/adi_vip/index.rst

@@ -0,0 +1,12 @@
+.. _adi_vip:
+
+ADI VIPs
+================================================================================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   ADI VIP Template <adi_vip_template/index>

docs/library/custom_ip/custom_ip_template/index.rst

@@ -0,0 +1,28 @@
+.. _custom_ip_template:
+
+ADI VIP
+================================================================================
+
+Description
+
+Features
+--------------------------------------------------------------------------------
+
+Files
+--------------------------------------------------------------------------------
+
+Configuration parameters
+--------------------------------------------------------------------------------
+
+Functions
+--------------------------------------------------------------------------------
+
+Known Issues
+--------------------------------------------------------------------------------
+
+Technical Support
+--------------------------------------------------------------------------------
+
+References
+--------------------------------------------------------------------------------
+

docs/library/custom_ip/index.rst

@@ -0,0 +1,12 @@
+.. _custom_ip:
+
+Custom IPs
+================================================================================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   Custom IP Template <custom_ip_template/index>

docs/library/index.rst

@@ -0,0 +1,37 @@
+.. _library:
+
+IP Cores
+===============================================================================
+
+ADI VIP
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   adi_vip/index
+
+Custom IP
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   custom_ip/index
+
+Utilities
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   utilities/index     
+
+Xilinx VIP
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   xilinx_vip/index
+

docs/library/utilities/index.rst

@@ -0,0 +1,14 @@
+.. _utilities:
+
+Utilities
+================================================================================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   Monitor <monitor/index>
+   Scoreboard <scoreboard/index>
+   Watchdog <watchdog/index>

docs/library/utilities/monitor/index.rst

@@ -0,0 +1,5 @@
+.. _monitor:
+
+Monitor
+================================================================================
+

docs/library/utilities/scoreboard/index.rst

@@ -0,0 +1,5 @@
+.. _scoreboard:
+
+Scoreboard
+================================================================================
+

docs/library/utilities/watchdog/index.rst

@@ -0,0 +1,5 @@
+.. _watchdog:
+
+Watchdog
+================================================================================
+

docs/library/xilinx_vip/axi_vip/index.rst

@@ -0,0 +1,29 @@
+.. _xilinx_axi_vip:
+
+Xilinx AXI Verification IP (VIP)
+================================================================================
+
+Description
+
+`[1] <https://docs.amd.com/r/en-US/pg267-axi-vip>`__
+
+m_axi_sequencer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files
+
+Functions
+
+s_axi_sequencer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files
+
+Functions
+
+References
+-------------------------------------------------------------------------------
+
+`[1] "AXI Verification IP LogiCORE IP Product Guide (PG267)", Xilinx, 2019
+<https://docs.amd.com/r/en-US/pg267-axi-vip>`__
+

docs/library/xilinx_vip/axis_vip/index.rst

@@ -0,0 +1,28 @@
+.. _xilinx_axis_vip:
+
+Xilinx AXI Stream Verification IP (VIP)
+================================================================================
+
+Description
+
+`[1] <https://docs.amd.com/v/u/en-US/pg277-axi4stream-vip>`__
+
+m_axi_sequencer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files
+
+Functions
+
+s_axi_sequencer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files
+
+Functions
+
+References
+-------------------------------------------------------------------------------
+
+`[1] "AXI4-Stream Verification IP v1.1 LogiCORE IP Product Guide (PG277)",
+Xilinx, 2019 <https://docs.amd.com/v/u/en-US/pg277-axi4stream-vip>`__