Add documentation support (#114)

docs: Initial commit

Signed-off-by: Jorge Marques <[email protected]>
Signed-off-by: Stanca Pop <[email protected]>
Co-authored-by: Jorge Marques <[email protected]>

.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 = 'testbenches'
+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.47'
+}
+
+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 included 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
+   testbenches/index

docs/library/drivers/common/index.rst

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

docs/library/drivers/common/monitor/index.rst

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

docs/library/drivers/common/scoreboard/index.rst

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

docs/library/drivers/common/watchdog/index.rst

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

docs/library/drivers/data_offload/index.rst

@@ -0,0 +1,5 @@
+.. _data_offload:
+
+Data Offload
+================================================================================
+

docs/library/drivers/dmac/index.rst

@@ -0,0 +1,5 @@
+.. _dmac:
+
+DMAC
+================================================================================
+

docs/library/drivers/index.rst

@@ -0,0 +1,17 @@
+.. _drivers:
+
+Drivers
+================================================================================
+
+Contents
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   common/index
+   data_offload/index
+   dmac/index
+   jesd/index
+   spi_engine/index
+   xcvr/index

docs/library/drivers/jesd/index.rst

@@ -0,0 +1,5 @@
+.. _jesd:
+
+JESD
+================================================================================
+

docs/library/drivers/spi_engine/index.rst

@@ -0,0 +1,5 @@
+.. _spi_engine:
+
+SPI Engine
+================================================================================
+

docs/library/drivers/xcvr/index.rst

@@ -0,0 +1,5 @@
+.. _xcvr:
+
+XCVR
+================================================================================
+

docs/library/index.rst

@@ -0,0 +1,37 @@
+.. _library:
+
+Library
+===============================================================================
+
+Drivers
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   drivers/index
+
+Registermaps
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   regmaps/index
+
+Utilities
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   utilities/index
+
+VIPs
+-------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   vip/index
+

docs/library/regmaps/index.rst

@@ -0,0 +1,8 @@
+.. _regmaps:
+
+Registermaps
+================================================================================
+
+Contents
+--------
+

docs/library/utilities/index.rst

@@ -0,0 +1,11 @@
+.. _utilities:
+
+Utilities
+================================================================================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+

docs/library/vip/adi/index.rst

@@ -0,0 +1,13 @@
+.. _adi_vip:
+
+ADI VIPs
+================================================================================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   SPI VIP <spi_vip/index>
+

docs/library/vip/adi/spi_vip/index.rst

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