mirror of
https://github.com/ROCm/ROCm.git
synced 2026-01-07 22:03:58 -05:00
Docs: use custom directive to reference library versions
This commit is contained in:
Adel Johar
1
.gitignore
vendored
1
.gitignore
vendored
@@ -11,6 +11,7 @@ _toc.yml
|
||||
docBin/
|
||||
_doxygen/
|
||||
_readthedocs/
|
||||
__pycache__/
|
||||
|
||||
# avoid duplicating contributing.md due to conf.py
|
||||
docs/CHANGELOG.md
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
11
docs/conf.py
11
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/")
|
||||
|
||||
0
docs/extension/__init__.py
Normal file
0
docs/extension/__init__.py
Normal file
266
docs/extension/version-ref.py
Normal file
266
docs/extension/version-ref.py
Normal file
@@ -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,
|
||||
}
|
||||
Reference in New Issue
Block a user