feat: add docs for SPC-X optimizations

introduce rli:: directive for remote literal includes

Add scaffolding to repo.sh to substitute version in links before build
and for cleaning up after

Signed-off-by: Alexander Maslennikov <[email protected]>

Author: almaslennikov

Makefile

@@ -171,7 +171,7 @@ build-cache:
 		# Add commands to populate the cache here \
 		export PM_PACKAGES_ROOT=${CACHE_DIR}; \
 		${CURDIR}/repo.sh docs || true; \
-		${CURDIR}/tools/packman/python.sh -m pip install --no-cache-dir --no-deps -U -t ${CACHE_DIR}/chk/sphinx/4.5.0.2-py3.7-linux-x86_64/ Sphinx-Substitution-Extensions; \
+		${CURDIR}/tools/packman/python.sh -m pip install --no-cache-dir --no-deps -U -t ${CACHE_DIR}/chk/sphinx/4.5.0.2-py3.7-linux-x86_64/ Sphinx-Substitution-Extensions sphinxext-remoteliteralinclude; \
 	fi
 
 .PHONY: process-examples

docs/nic-conf-operator/nic-configuration-operator.rst

@@ -26,4 +26,5 @@ NIC Configuration Operator
 
    NIC Firmware Configuration <nic-fw-configuration.rst>
    Configuration Details <configuration-details.rst>
+   [TECH PREVIEW] Spectrum-X Configuration <spectrum-x-configuration.rst>
    CRD API Reference <crds.rst>

docs/nic-conf-operator/nic-fw-configuration.rst

@@ -146,22 +146,9 @@ Configure and apply the NICFirmwareSource CR
 
 Deploy the NICFirmwareSource CR:
 
-.. code-block:: yaml
-
-    apiVersion: configuration.net.nvidia.com/v1alpha1
-    kind: NicFirmwareSource
-    metadata:
-      name: connectx6-dx-firmware-22-44-1036
-      namespace: nvidia-network-operator
-      finalizers:
-        - configuration.net.nvidia.com/nic-configuration-operator
-    spec:
-      # a list of firmware binaries zip archives from the Mellanox website, can point to any URL accessible from the cluster
-      binUrlSources:
-        - https://www.mellanox.com/downloads/firmware/fw-ConnectX6Dx-rel-22_44_1036-MCX623106AC-CDA_Ax-UEFI-14.37.14-FlexBoot-3.7.500.signed.bin.zip
-      # a URL to the BlueField Bundle (BFB) file, can point to any URL accessible from the cluster
-      bfbUrlSource:
-        - https://example.com/bf-fwbundle-3.1.0-77_25.07-prod.bfb
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicfwsource-connectx6dx.yaml
+    :language: yaml
+    :lines: 18-
 
 .. note::
     The ConnectX firmware binaries can be downloaded from the `NVIDIA Networking Firmware Downloads page <https://network.nvidia.com/support/firmware/firmware-downloads/>`_.
@@ -190,21 +177,9 @@ Configure and apply the NicFirmwareTemplate CR
 
 Configure and apply the NicFirmwareTemplate CR:
 
-.. code-block:: yaml
-
-    apiVersion: configuration.net.nvidia.com/v1alpha1
-    kind: NicFirmwareTemplate
-    metadata:
-      name: connectx6dx-config
-      namespace: nvidia-network-operator
-    spec:
-      nodeSelector:
-        kubernetes.io/hostname: node1
-      nicSelector:
-        nicType: "101d"
-      template:
-        nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036
-        updatePolicy: Update
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicfirmwaretemplate-connectx6-dx.yaml
+    :language: yaml
+    :lines: 18-
 
 Spec of the NicDevice CR is updated in accordance with the NICFirmwareTemplate and NicConfigurationTemplate CRs matching the device
 
@@ -267,40 +242,9 @@ Configure NIC Firmware using the NIC Configuration Operator
 Configure and apply the NicConfigurationTemplate CR
 ---------------------------------------------------
 
-.. code-block:: yaml
-
-    apiVersion: configuration.net.nvidia.com/v1alpha1
-    kind: NicConfigurationTemplate
-    metadata:
-       name: connectx6-config
-       namespace: nvidia-network-operator
-    spec:
-       nodeSelector:
-          feature.node.kubernetes.io/network-sriov.capable: "true"
-       nicSelector:
-          # nicType selector is mandatory the rest are optional. Only a single type can be specified.
-          nicType: 101d
-          pciAddresses:
-             - "0000:03:00.0"
-             - “0000:04:00.0”
-          serialNumbers:
-             - "mt1952x03327"
-       resetToDefault: false # if set, template is ignored, device configuration should reset
-       template:
-          # numVfs and linkType fields are mandatory, the rest are optional
-          numVfs: 2
-          linkType: Ethernet
-          pciPerformanceOptimized:
-             enabled: true
-             maxReadRequest: 4096
-          roceOptimized:
-             enabled: true
-             qos:
-                trust: dscp
-                pfc: "0,0,0,1,0,0,0,0"
-          gpuDirectOptimized:
-             enabled: true
-             env: Baremetal
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicconfigurationtemplate-connectx6dx.yaml
+    :language: yaml
+    :lines: 18-
 
 .. note:: It's not possible to apply more than one template of each kind (NICFirmwareTemplate or NICConfigurationTemplate) to a single device. In this case, no template will be applied and an error event will be emitted for the corresponding NicDevice CR.
 

docs/nic-conf-operator/spectrum-x-configuration.rst

@@ -0,0 +1,83 @@
+.. license-header
+  SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+.. headings # #, * *, =, -, ^, "
+
+.. include:: ../common/vars.rst
+
+**************************************************
+[TECH PREVIEW] NVIDIA Spectrum-X NIC Configuration
+**************************************************
+
+.. contents:: On this page
+   :depth: 4
+   :local:
+   :backlinks: none
+
+
+`NVIDIA NIC Configuration Operator <https://github.com/Mellanox/nic-configuration-operator>`_ offers NVIDIA Spectrum-X-specific NIC configuration for different versions of the Reference Architecture.
+
+.. note:: Currently, only ConnectX-8 (device ID 1023) and BlueField-3 SuperNIC (device ID a2dc) devices are supported for this configuration.
+
+.. warning:: Tech Preview feature.
+
+====================================================
+Install and configure the NIC Configuration Operator
+====================================================
+
+To install the operator and for more information about the CRDs follow the `NIC FW Configuration <nic-fw-configuration.rst>`_ and `Configuration Details <configuration-details.rst>`_ doc articles.
+
+=============================================
+Provision the DOCA SPC-X CC algorithm package
+=============================================
+
+To enable the DOCA SPC-X CC algorithm on NIC devices, the DOCA SPC-X CC .deb package for ubuntu 22.04 is required. This configuration step will be removed in the future, once the DOCA SPC-X CC algorithm will be publicly available.
+To access the package, contact your NVIDIA CPM.
+The package should be made available in the cluster and then its URL should be provided in the packageUrlSource field of the SpectrumXOperator CR.
+
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaresource-spectrum-x-cc-only.yaml
+    :language: yaml
+    :lines: 18-
+
+If firmware on the devices also needs to be updated, extend the NicFirmwareSource CR with fields for ConnectX and BlueField firmware. Please, use the correct firmware for your devices.
+
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaresource-spectrum-x-full.yaml
+    :language: yaml
+    :lines: 18-
+
+Configure and apply the NicFirmwareTemplate CR:
+
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaretemplate-spectrum-x.yaml
+    :language: yaml
+    :lines: 18-
+
+======================================
+Enable SPC-X optimizations for devices
+======================================
+
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicconfigurationtemplate-spectrum-x.yaml
+    :language: yaml
+    :lines: 18-
+
+---------------------
+Configuration details
+---------------------
+
+Following configuration parameters are applied with spectrumXOptimized.enabled == true and spectrumXOptimized.version == "RA2.0":
+
+.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/bindata/spectrum-x/RA2.0.yaml
+    :language: yaml
+    :lines: 17-

repo.sh

@@ -5,4 +5,37 @@ set -e
 SCRIPT_DIR=$(dirname ${BASH_SOURCE})
 cd "$SCRIPT_DIR"
 
-exec "tools/packman/python.sh" tools/repoman/repoman.py $@
+if [ "${1:-}" = "docs" ]; then
+    echo "Processing RST files for rli:: variable substitutions..."
+    # Forward substitutions script: |var| -> value (applies only to lines with 'rli::')
+    sed_file_f=/tmp/vars_rli.sed
+    grep -E '^\.\. \|.*\| replace::' docs/common/vars.rst | \
+        sed 's/\.\. |\(.*\)| replace:: \(.*\)/\/rli::\/ s@|\1|@\2@g/' > "$sed_file_f"
+    # Apply in-place only to matching files (those that contain rli::)
+    grep -RIl --include="*.rst" --exclude-dir="_build" 'rli::' docs | while read -r file; do
+        echo "Processing $file"
+        sed -i -f "$sed_file_f" "$file"
+    done
+fi
+
+# Run the documentation build (do not exec so we can run post-steps)
+set +e
+"tools/packman/python.sh" tools/repoman/repoman.py "$@"
+rc=$?
+set -e
+
+if [ "${1:-}" = "docs" ]; then
+    echo "Reverting rli:: substitutions in RST files..."
+    # Reverse substitutions script: value -> |var| (applies only to lines with 'rli::')
+    sed_file_r=/tmp/vars_rli_rev.sed
+    grep -E '^\.\. \|.*\| replace::' docs/common/vars.rst | \
+        sed 's/\.\. |\(.*\)| replace:: \(.*\)/\/rli::\/ s@\2@|\1|@g/' > "$sed_file_r"
+    grep -RIl --include="*.rst" --exclude-dir="_build" 'rli::' docs | while read -r file; do
+        echo "Processing $file"
+        sed -i -f "$sed_file_r" "$file"
+    done
+    # Cleanup both scripts if present
+    rm -f /tmp/vars_rli.sed "$sed_file_r"
+fi
+
+exit $rc

repo.toml

@@ -13,7 +13,7 @@ social_media_set = []
 social_media = []
 favicon = "${root}/assets/favicon.ico"
 logo = "${root}/assets/nvidia-logo-white.png"
-extensions_extra = ['sphinx_substitution_extensions']
+extensions_extra = ['sphinx_substitution_extensions', 'sphinxext.remoteliteralinclude']
 
 [repo_docs.builds.linkcheck]
 build_by_default = false