Docs: use custom directive to reference library versions

.gitignore

@@ -11,6 +11,7 @@ _toc.yml
 docBin/
 _doxygen/
 _readthedocs/
+__pycache__/
 
 # avoid duplicating contributing.md due to conf.py
 docs/CHANGELOG.md

docs/compatibility/ml-compatibility/jax-compatibility.rst

@@ -4,6 +4,8 @@
    :description: JAX compatibility
    :keywords: GPU, JAX compatibility
 
+.. version-set:: rocm_version latest
+
 *******************************************************************************
 JAX compatibility
 *******************************************************************************
@@ -119,7 +121,8 @@ Critical ROCm libraries for JAX
 
 The functionality of JAX with ROCm is determined by its underlying library
 dependencies. These critical ROCm components affect the capabilities,
-performance, and feature set available to developers.
+performance, and feature set available to developers. The versions described
+are available in ROCm :version:`rocm_version`.
 
 .. list-table::
     :header-rows: 1
@@ -129,7 +132,7 @@ performance, and feature set available to developers.
       - Purpose
       - Used in
     * - `hipBLAS <https://github.com/ROCm/hipBLAS>`_
-      - 2.3.0
+      - :version-ref:`hipBLAS rocm_version`
       - Provides GPU-accelerated Basic Linear Algebra Subprograms (BLAS) for
         matrix and vector operations.
       - Matrix multiplication in ``jax.numpy.matmul``, ``jax.lax.dot`` and
@@ -138,7 +141,7 @@ performance, and feature set available to developers.
         ``jax.numpy.einsum`` with matrix-multiplication patterns algebra
         operations.
     * - `hipBLASLt <https://github.com/ROCm/hipBLASLt>`_
-      - 0.10.0
+      - :version-ref:`hipBLASLt rocm_version`
       - hipBLASLt is an extension of hipBLAS, providing additional
         features like epilogues fused into the matrix multiplication kernel or
         use of integer tensor cores.
@@ -147,7 +150,7 @@ performance, and feature set available to developers.
         operations, mixed-precision support, and hardware-specific
         optimizations.
     * - `hipCUB <https://github.com/ROCm/hipCUB>`_
-      - 3.3.0
+      - :version-ref:`hipCUB rocm_version`
       - Provides a C++ template library for parallel algorithms for reduction,
         scan, sort and select.
       - Reduction functions (``jax.numpy.sum``, ``jax.numpy.mean``,
@@ -155,23 +158,23 @@ performance, and feature set available to developers.
         (``jax.numpy.cumsum``, ``jax.numpy.cumprod``) and sorting
         (``jax.numpy.sort``, ``jax.numpy.argsort``).
     * - `hipFFT <https://github.com/ROCm/hipFFT>`_
-      - 1.0.17
+      - :version-ref:`hipFFT rocm_version`
       - Provides GPU-accelerated Fast Fourier Transform (FFT) operations.
       - Used in functions like ``jax.numpy.fft``.
     * - `hipRAND <https://github.com/ROCm/hipRAND>`_
-      - 2.11.0
+      - :version-ref:`hipRAND rocm_version`
       - Provides fast random number generation for GPUs.
       - The ``jax.random.uniform``, ``jax.random.normal``,
         ``jax.random.randint`` and ``jax.random.split``.
     * - `hipSOLVER <https://github.com/ROCm/hipSOLVER>`_
-      - 2.3.0
+      - :version-ref:`hipSOLVER rocm_version`
       - Provides GPU-accelerated solvers for linear systems, eigenvalues, and
         singular value decompositions (SVD).
       - Solving linear systems (``jax.numpy.linalg.solve``), matrix
         factorizations, SVD (``jax.numpy.linalg.svd``) and eigenvalue problems
         (``jax.numpy.linalg.eig``).
     * - `hipSPARSE <https://github.com/ROCm/hipSPARSE>`_
-      - 3.1.2
+      - :version-ref:`hipSPARSE rocm_version`
       - Accelerates operations on sparse matrices, such as sparse matrix-vector
         or matrix-matrix products.
       - Sparse matrix multiplication (``jax.numpy.matmul``), sparse
@@ -179,28 +182,28 @@ performance, and feature set available to developers.
         (``jax.experimental.sparse.dot``), sparse linear system solvers and
         sparse data handling.
     * - `hipSPARSELt <https://github.com/ROCm/hipSPARSELt>`_
-      - 0.2.2
+      - :version-ref:`hipSPARSELt rocm_version`
       - Accelerates operations on sparse matrices, such as sparse matrix-vector
         or matrix-matrix products.
       - Sparse matrix multiplication (``jax.numpy.matmul``), sparse
         matrix-vector and matrix-matrix products
         (``jax.experimental.sparse.dot``) and sparse linear system solvers.
     * - `MIOpen <https://github.com/ROCm/MIOpen>`_
-      - 3.3.0
+      - :version-ref:`MIOpen rocm_version`
       - Optimized for deep learning primitives such as convolutions, pooling,
         normalization, and activation functions.
       - Speeds up convolutional neural networks (CNNs), recurrent neural
         networks (RNNs), and other layers. Used in operations like
         ``jax.nn.conv``, ``jax.nn.relu``, and ``jax.nn.batch_norm``.
     * - `RCCL <https://github.com/ROCm/rccl>`_
-      - 2.21.5
+      - :version-ref:`RCCL rocm_version`
       - Optimized for multi-GPU communication for operations like  all-reduce,
         broadcast, and scatter.
       - Distribute computations across multiple GPU with ``pmap`` and
         ``jax.distributed``. XLA automatically uses rccl when executing
         operations across multiple GPUs on AMD hardware.
     * - `rocThrust <https://github.com/ROCm/rocThrust>`_
-      - 3.3.0
+      - :version-ref:`rocThrust rocm_version`
       - Provides a C++ template library for parallel algorithms like sorting,
         reduction, and scanning.
       - Reduction operations like ``jax.numpy.sum``, ``jax.pmap`` for

docs/compatibility/ml-compatibility/pytorch-compatibility.rst

@@ -4,6 +4,8 @@
     :description: PyTorch compatibility
     :keywords: GPU, PyTorch compatibility
 
+.. version-set:: rocm_version latest
+
 ********************************************************************************
 PyTorch compatibility
 ********************************************************************************
@@ -200,7 +202,8 @@ Critical ROCm libraries for PyTorch
 
 The functionality of PyTorch with ROCm is determined by its underlying library
 dependencies. These critical ROCm components affect the capabilities,
-performance, and feature set available to developers.
+performance, and feature set available to developers. The versions described
+are available in ROCm :version:`rocm_version`.
 
 .. list-table::
     :header-rows: 1
@@ -210,28 +213,28 @@ performance, and feature set available to developers.
       - Purpose
       - Used in
     * - `Composable Kernel <https://github.com/ROCm/composable_kernel>`_
-      - 1.1.0
+      - :version-ref:`"Composable Kernel" rocm_version`
       - Enables faster execution of core operations like matrix multiplication
         (GEMM), convolutions and transformations.
       - Speeds up ``torch.permute``, ``torch.view``, ``torch.matmul``,
         ``torch.mm``, ``torch.bmm``, ``torch.nn.Conv2d``, ``torch.nn.Conv3d``
         and ``torch.nn.MultiheadAttention``.
     * - `hipBLAS <https://github.com/ROCm/hipBLAS>`_
-      - 2.3.0
+      - :version-ref:`hipBLAS rocm_version`
       - Provides GPU-accelerated Basic Linear Algebra Subprograms (BLAS) for
         matrix and vector operations.
       - Supports operations like matrix multiplication, matrix-vector products,
         and tensor contractions. Utilized in both dense and batched linear
         algebra operations.
     * - `hipBLASLt <https://github.com/ROCm/hipBLASLt>`_
-      - 0.10.0
+      - :version-ref:`hipBLASLt rocm_version`
       - hipBLASLt is an extension of the hipBLAS library, providing additional
         features like epilogues fused into the matrix multiplication kernel or
         use of integer tensor cores.
       - It accelerates operations like ``torch.matmul``, ``torch.mm``, and the
         matrix multiplications used in convolutional and linear layers.
     * - `hipCUB <https://github.com/ROCm/hipCUB>`_
-      - 3.3.0
+      - :version-ref:`hipCUB rocm_version`
       - Provides a C++ template library for parallel algorithms for reduction,
         scan, sort and select.
       - Supports operations like ``torch.sum``, ``torch.cumsum``, ``torch.sort``
@@ -239,93 +242,93 @@ performance, and feature set available to developers.
         irregular shapes often involve scanning, sorting, and filtering, which
         hipCUB handles efficiently.
     * - `hipFFT <https://github.com/ROCm/hipFFT>`_
-      - 1.0.17
+      - :version-ref:`hipFFT rocm_version`
       - Provides GPU-accelerated Fast Fourier Transform (FFT) operations.
       - Used in functions like the ``torch.fft`` module.
     * - `hipRAND <https://github.com/ROCm/hipRAND>`_
-      - 2.11.0
+      - :version-ref:`hipRAND rocm_version`
       - Provides fast random number generation for GPUs.
       - The ``torch.rand``, ``torch.randn`` and stochastic layers like
         ``torch.nn.Dropout``.
     * - `hipSOLVER <https://github.com/ROCm/hipSOLVER>`_
-      - 2.3.0
+      - :version-ref:`hipSOLVER rocm_version`
       - Provides GPU-accelerated solvers for linear systems, eigenvalues, and
         singular value decompositions (SVD).
       - Supports functions like ``torch.linalg.solve``,
         ``torch.linalg.eig``, and ``torch.linalg.svd``.
     * - `hipSPARSE <https://github.com/ROCm/hipSPARSE>`_
-      - 3.1.2
+      - :version-ref:`hipSPARSE rocm_version`
       - Accelerates operations on sparse matrices, such as sparse matrix-vector
         or matrix-matrix products.
       - Sparse tensor operations ``torch.sparse``.
     * - `hipSPARSELt <https://github.com/ROCm/hipSPARSELt>`_
-      - 0.2.2
+      - :version-ref:`hipSPARSELt rocm_version`
       - Accelerates operations on sparse matrices, such as sparse matrix-vector
         or matrix-matrix products.
       - Sparse tensor operations ``torch.sparse``.
     * - `hipTensor <https://github.com/ROCm/hipTensor>`_
-      - 1.4.0
+      - :version-ref:`hipTensor rocm_version`
       - Optimizes for high-performance tensor operations, such as contractions.
       - Accelerates tensor algebra, especially in deep learning and scientific
         computing.
     * - `MIOpen <https://github.com/ROCm/MIOpen>`_
-      - 3.3.0
+      - :version-ref:`MIOpen rocm_version`
       - Optimizes deep learning primitives such as convolutions, pooling,
         normalization, and activation functions.
       - Speeds up convolutional neural networks (CNNs), recurrent neural
         networks (RNNs), and other layers. Used in operations like
         ``torch.nn.Conv2d``, ``torch.nn.ReLU``, and ``torch.nn.LSTM``.
     * - `MIGraphX <https://github.com/ROCm/AMDMIGraphX>`_
-      - 2.11.0
+      - :version-ref:`MIGraphX rocm_version`
       - Adds graph-level optimizations, ONNX models and mixed precision support
         and enable Ahead-of-Time (AOT) Compilation.
       - Speeds up inference models and executes ONNX models for
         compatibility with other frameworks.
         ``torch.nn.Conv2d``, ``torch.nn.ReLU``, and ``torch.nn.LSTM``.
     * - `MIVisionX <https://github.com/ROCm/MIVisionX>`_
-      - 3.1.0
+      - :version-ref:`MIVisionX rocm_version`
       - Optimizes acceleration for computer vision and AI workloads like
         preprocessing, augmentation, and inferencing.
       - Faster data preprocessing and augmentation pipelines for datasets like
         ImageNet or COCO and easy to integrate into PyTorch's ``torch.utils.data``
         and ``torchvision`` workflows.
     * - `rocAL <https://github.com/ROCm/rocAL>`_
-      - 2.1.0
+      - :version-ref:`rocAL rocm_version`
       - Accelerates the data pipeline by offloading intensive preprocessing and
         augmentation tasks. rocAL is part of MIVisionX.
       - Easy to integrate into PyTorch's ``torch.utils.data`` and
         ``torchvision`` data load workloads.
     * - `RCCL <https://github.com/ROCm/rccl>`_
-      - 2.21.5
+      - :version-ref:`RCCL rocm_version`
       - Optimizes for multi-GPU communication for operations like AllReduce and
         Broadcast.
       - Distributed data parallel training (``torch.nn.parallel.DistributedDataParallel``).
         Handles communication in multi-GPU setups.
     * - `rocDecode <https://github.com/ROCm/rocDecode>`_
-      - 0.8.0
+      - :version-ref:`rocDecode rocm_version`
       - Provides hardware-accelerated data decoding capabilities, particularly
         for image, video, and other dataset formats.
       - Can be integrated in ``torch.utils.data``, ``torchvision.transforms``
         and ``torch.distributed``.
     * - `rocJPEG <https://github.com/ROCm/rocJPEG>`_
-      - 0.6.0
+      - :version-ref:`rocJPEG rocm_version`
       - Provides hardware-accelerated JPEG image decoding and encoding.
       - GPU accelerated ``torchvision.io.decode_jpeg`` and
         ``torchvision.io.encode_jpeg`` and can be integrated in
         ``torch.utils.data`` and ``torchvision``.
     * - `RPP <https://github.com/ROCm/RPP>`_
-      - 1.9.1
+      - :version-ref:`RPP rocm_version`
       - Speeds up data augmentation, transformation, and other preprocessing steps.
       - Easy to integrate into PyTorch's ``torch.utils.data`` and
         ``torchvision`` data load workloads.
     * - `rocThrust <https://github.com/ROCm/rocThrust>`_
-      - 3.3.0
+      - :version-ref:`rocThrust rocm_version`
       - Provides a C++ template library for parallel algorithms like sorting,
         reduction, and scanning.
       - Utilized in backend operations for tensor computations requiring
         parallel processing.
     * - `rocWMMA <https://github.com/ROCm/rocWMMA>`_
-      - 1.6.0
+      - :version-ref:`rocWMMA rocm_version`
       - Accelerates warp-level matrix-multiply and matrix-accumulate to speed up matrix
         multiplication (GEMM) and accumulation operations with mixed precision
         support.

docs/compatibility/ml-compatibility/tensorflow-compatibility.rst

@@ -4,6 +4,8 @@
     :description: TensorFlow compatibility
     :keywords: GPU, TensorFlow compatibility
 
+.. version-set:: rocm_version latest
+
 *******************************************************************************
 TensorFlow compatibility
 *******************************************************************************
@@ -117,7 +119,8 @@ Critical ROCm libraries for TensorFlow
 TensorFlow depends on multiple components and the supported features of those
 components can affect the TensorFlow ROCm supported feature set. The versions
 in the following table refer to the first TensorFlow version where the ROCm
-library was introduced as a dependency.
+library was introduced as a dependency. The versions described
+are available in ROCm :version:`rocm_version`.
 
 .. list-table::
     :widths: 25, 10, 35, 30
@@ -128,43 +131,43 @@ library was introduced as a dependency.
       - Purpose
       - Used in
     * - `hipBLAS <https://github.com/ROCm/hipBLAS>`_
-      - 2.3.0
+      - :version-ref:`hipBLAS rocm_version`
       - Provides GPU-accelerated Basic Linear Algebra Subprograms (BLAS) for
         matrix and vector operations.
       - Accelerates operations like ``tf.matmul``, ``tf.linalg.matmul``, and
         other matrix multiplications commonly used in neural network layers.
     * - `hipBLASLt <https://github.com/ROCm/hipBLASLt>`_
-      - 0.10.0
+      - :version-ref:`hipBLASLt rocm_version`
       - Extends hipBLAS with additional optimizations like fused kernels and
         integer tensor cores.
       - Optimizes matrix multiplications and linear algebra operations used in
         layers like dense, convolutional, and RNNs in TensorFlow.
     * - `hipCUB <https://github.com/ROCm/hipCUB>`_
-      - 3.3.0
+      - :version-ref:`hipCUB rocm_version`
       - Provides a C++ template library for parallel algorithms for reduction,
         scan, sort and select.
       - Supports operations like ``tf.reduce_sum``, ``tf.cumsum``, ``tf.sort``
         and other tensor operations in TensorFlow, especially those involving
         scanning, sorting, and filtering.
     * - `hipFFT <https://github.com/ROCm/hipFFT>`_
-      - 1.0.17
+      - :version-ref:`hipFFT rocm_version`
       - Accelerates Fast Fourier Transforms (FFT) for signal processing tasks.
       - Used for operations like signal processing, image filtering, and
         certain types of neural networks requiring FFT-based transformations.
     * - `hipSOLVER <https://github.com/ROCm/hipSOLVER>`_
-      - 2.3.0
+      - :version-ref:`hipSOLVER rocm_version`
       - Provides GPU-accelerated direct linear solvers for dense and sparse
         systems.
       - Optimizes linear algebra functions such as solving systems of linear
         equations, often used in optimization and training tasks.
     * - `hipSPARSE <https://github.com/ROCm/hipSPARSE>`_
-      - 3.1.2
+      - :version-ref:`hipSPARSE rocm_version`
       - Optimizes sparse matrix operations for efficient computations on sparse
         data.
       - Accelerates sparse matrix operations in models with sparse weight
         matrices or activations, commonly used in neural networks.
     * - `MIOpen <https://github.com/ROCm/MIOpen>`_
-      - 3.3.0
+      - :version-ref:`MIOpen rocm_version`
       - Provides optimized deep learning primitives such as convolutions,
         pooling,
         normalization, and activation functions.
@@ -172,13 +175,13 @@ library was introduced as a dependency.
         in TensorFlow for layers like ``tf.nn.conv2d``, ``tf.nn.relu``, and
         ``tf.nn.lstm_cell``.
     * - `RCCL <https://github.com/ROCm/rccl>`_
-      - 2.21.5
+      - :version-ref:`RCCL rocm_version`
       - Optimizes for multi-GPU communication for operations like AllReduce and
         Broadcast.
       - Distributed data parallel training (``tf.distribute.MirroredStrategy``).
         Handles communication in multi-GPU setups.
     * - `rocThrust <https://github.com/ROCm/rocThrust>`_
-      - 3.3.0
+      - :version-ref:`rocThrust rocm_version`
       - Provides a C++ template library for parallel algorithms like sorting,
         reduction, and scanning.
       - Reduction operations like ``tf.reduce_sum``, ``tf.cumsum`` for computing

docs/conf.py

@@ -6,6 +6,8 @@
 
 import os
 import shutil
+import sys
+from pathlib import Path
 
 shutil.copy2("../RELEASE.md", "./about/release-notes.md")
 
@@ -89,11 +91,16 @@ article_pages = [
 
 external_toc_path = "./sphinx/_toc.yml"
 
-extensions = ["rocm_docs", "sphinx_reredirects", "sphinx_sitemap", "sphinxcontrib.datatemplates"]
+# Add the _extensions directory to Python's search path
+sys.path.append(str(Path(__file__).parent / 'extension'))
+
+extensions = ["rocm_docs", "sphinx_reredirects", "sphinx_sitemap", "sphinxcontrib.datatemplates", "version-ref"]
+
+compatibility_matrix_file = str(Path(__file__).parent / 'compatibility/compatibility-matrix-historical-6.0.csv')
 
 external_projects_current_project = "rocm"
 
-# Uncomment if facing rate limit exceed issue with local build 
+# Uncomment if facing rate limit exceed issue with local build
 # external_projects_remote_repository = ""
 
 html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "https://rocm-stg.amd.com/")

docs/extension/version-ref.py

@@ -0,0 +1,266 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.util import logging
+import csv
+from io import StringIO
+import re
+import shlex
+
+logger = logging.getLogger(__name__)
+
+class VersionReference(nodes.Inline, nodes.TextElement):
+    """Represents an inline version reference."""
+    pass
+
+class VersionSetDirective(Directive):
+    """Directive for setting version references within a page scope."""
+    required_arguments = 2  # name and value
+    optional_arguments = 0
+
+    def run(self):
+        env = self.state.document.settings.env
+        if not hasattr(env, 'doc_version_refs'):
+            env.doc_version_refs = {}
+        current_doc = env.docname
+        if current_doc not in env.doc_version_refs:
+            env.doc_version_refs[current_doc] = {}
+
+        name, value = self.arguments
+        if name.lower() == 'latest':
+            logger.warning('Cannot override the "latest" keyword with version-set')
+            return []
+
+        # Handle 'latest' value by getting the actual version
+        if value.lower() == 'latest':
+            data = getattr(env, 'compatibility_matrix', None)
+            if data:
+                latest_version = get_latest_rocm_version(data)
+                if latest_version:
+                    value = latest_version
+
+        env.doc_version_refs[current_doc][name] = value
+        return []
+
+def clean_library_name(name):
+    """Extract library name from RST formatting."""
+    # Handle :doc: format
+    doc_match = re.search(r':doc:`([^<]+)(?:\s+<[^>]+>)?`', name)
+    if doc_match:
+        return doc_match.group(1).strip()
+
+    # Handle other link formats
+    link_match = re.search(r'`([^<]+)(?:\s+<[^>]+>)?`_?', name)
+    if link_match:
+        return link_match.group(1).strip()
+
+    return name.strip()
+
+def get_latest_rocm_version(data):
+    """Get the latest ROCm version from the matrix headers."""
+    if not data or len(data) == 0:
+        return None
+
+    # Get all column names except 'ROCm Version'
+    columns = [col for col in data[0].keys() if col != 'ROCm Version']
+    # Return the first column name (assumed to be the latest version)
+    return columns[0] if columns else None
+
+def version_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """
+    Role function to print version value.
+    Usage: :version:`version_name`
+    """
+    try:
+        version_name = text.strip()
+        env = inliner.document.settings.env
+
+        if hasattr(env, 'doc_version_refs'):
+            current_doc = env.docname
+            if current_doc in env.doc_version_refs:
+                doc_refs = env.doc_version_refs[current_doc]
+                if version_name in doc_refs:
+                    version = doc_refs[version_name]
+                    node = nodes.Text(version)
+                    return [node], []
+
+        msg = inliner.reporter.warning(
+            f'No version defined for name {version_name}',
+            line=lineno
+        )
+        return [], [msg]
+
+    except Exception as e:
+        msg = inliner.reporter.error(
+            f'Error looking up version: {str(e)}',
+            line=lineno
+        )
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+def version_ref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """
+    Role function for version references.
+    Usage: :version-ref:`library_name release`
+           :version-ref:`"library name" release`
+           :version-ref:`library_name latest`
+           :version-ref:`rocm latest`
+    """
+    try:
+        # Parse the text - handle both quoted and unquoted formats
+        if '"' in text:
+            parts = shlex.split(text)
+        else:
+            parts = text.split()
+
+        if len(parts) != 2:
+            msg = inliner.reporter.error(
+                'Version reference must be in format "library_name release" or "\\"library name\\" release"',
+                line=lineno
+            )
+            prb = inliner.problematic(rawtext, rawtext, msg)
+            return [prb], [msg]
+
+        library_name, release = parts
+        env = inliner.document.settings.env
+
+        # Check if release is a version reference in current document
+        if hasattr(env, 'doc_version_refs'):
+            current_doc = env.docname
+            if current_doc in env.doc_version_refs:
+                doc_refs = env.doc_version_refs[current_doc]
+                if release in doc_refs:
+                    release = doc_refs[release]
+
+        # Handle special case for "rocm latest"
+        if library_name.lower() == 'rocm' and release.lower() == 'latest':
+            data = getattr(env, 'compatibility_matrix', None)
+            if not data:
+                raise ValueError("Compatibility matrix not found in environment")
+
+            latest_version = get_latest_rocm_version(data)
+            if latest_version:
+                node = VersionReference()
+                node += nodes.Text(latest_version)
+                return [node], []
+            else:
+                msg = inliner.reporter.warning(
+                    'No ROCm versions found in compatibility matrix',
+                    line=lineno
+                )
+                return [], [msg]
+
+        version = lookup_version(inliner, library_name, release)
+
+        if version:
+            node = VersionReference()
+            node += nodes.Text(version)
+            return [node], []
+        else:
+            msg = inliner.reporter.warning(
+                f'No version found for library {library_name} in release {release}',
+                line=lineno
+            )
+            return [], [msg]
+
+    except Exception as e:
+        msg = inliner.reporter.error(
+            f'Error looking up version: {str(e)}',
+            line=lineno
+        )
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+def lookup_version(inliner, library_name, release):
+    """Look up the version in the compatibility matrix."""
+    env = inliner.document.settings.env
+    data = getattr(env, 'compatibility_matrix', None)
+
+    if not data:
+        raise ValueError("Compatibility matrix not found in environment")
+
+    # Handle the 'latest' keyword
+    if release.lower() == 'latest':
+        latest_version = get_latest_rocm_version(data)
+        if not latest_version:
+            return None
+        release = latest_version
+
+    # For ROCm, check if the version exists in column headers
+    if library_name.lower() == 'rocm':
+        columns = [col for col in data[0].keys() if col != 'ROCm Version']
+        if release in columns:
+            return release
+        return None
+
+    # Find the library version
+    for row in data:
+        row_lib_name = clean_library_name(row['ROCm Version'])
+        if row_lib_name == library_name:
+            # Get the version, removing any whitespace
+            version = row.get(release, '').strip()
+            if version:
+                return version
+
+    # If not found, try a case-insensitive search
+    for row in data:
+        row_lib_name = clean_library_name(row['ROCm Version'])
+        if row_lib_name.lower() == library_name.lower():
+            version = row.get(release, '').strip()
+            if version:
+                return version
+
+    return None
+
+def visit_version_reference(self, node):
+    self.body.append(f'<span class="version-reference">')
+
+def depart_version_reference(self, node):
+    self.body.append('</span>')
+
+def load_compatibility_matrix(app):
+    """Load the compatibility matrix content from CSV."""
+    if not app.config.compatibility_matrix_file:
+        logger.warning('No compatibility matrix file configured')
+        return
+
+    try:
+        with open(app.config.compatibility_matrix_file, 'r', encoding='utf-8') as f:
+            reader = csv.DictReader(f)
+            app.env.compatibility_matrix = list(reader)
+            logger.info('Successfully loaded compatibility matrix')
+
+            # Debug: print first few rows with their library names
+            for row in list(app.env.compatibility_matrix)[:5]:
+                if 'ROCm Version' in row:
+                    lib_name = clean_library_name(row['ROCm Version'])
+                    logger.debug(f"Loaded library: {lib_name}")
+
+    except Exception as e:
+        logger.error(f'Error loading compatibility matrix: {str(e)}')
+
+def purge_version_refs(app, env, docname):
+    """Remove version references for a document when it is purged"""
+    if hasattr(env, 'doc_version_refs'):
+        if docname in env.doc_version_refs:
+            del env.doc_version_refs[docname]
+
+def setup(app):
+    app.add_node(VersionReference,
+                 html=(visit_version_reference, depart_version_reference))
+    app.add_role('version-ref', version_ref_role)
+    app.add_role('version', version_role)
+    app.add_directive('version-set', VersionSetDirective)
+
+    # Add a config value for the compatibility matrix file path
+    app.add_config_value('compatibility_matrix_file', None, 'env')
+
+    # Connect to the builder-inited event to load the matrix
+    app.connect('builder-inited', load_compatibility_matrix)
+
+    # Connect to env-purge-doc event to clean up document-specific version refs
+    app.connect('env-purge-doc', purge_version_refs)
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }