docs: Update documentation generation. Make it mor verbose.

Author: mc-nv

docs/Dockerfile.docs

@@ -24,7 +24,7 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 # various documentation dependencies
 RUN apt-get update -q=2 \
@@ -53,6 +53,7 @@ RUN wget https://github.com/pseudomuto/protoc-gen-doc/releases/download/v1.3.2/p
     && rm /tmp/protoc-gen-doc.tar.gz
 
 # install sphinx et al
+ENV PIP_BREAK_SYSTEM_PACKAGES=1
 RUN pip3 install \
       ablog \
       attrs  \
@@ -75,8 +76,13 @@ RUN pip3 install \
       sphinxcontrib-bibtex
 
 RUN pip3 install \
-      --index-url https://urm.nvidia.com/artifactory/api/pypi/ct-omniverse-pypi/simple/ \
-      nvidia-sphinx-theme
+      --extra-index-url https://pypi.nvidia.com \
+      nvidia-sphinx-theme \
+      sphinx==7.4.7
+
+RUN curl -fL https://install-cli.jfrog.io | sh
+
+RUN git config --global --add safe.directory "*"
 
 # Set visitor script to be included on every HTML page
 ENV VISITS_COUNTING_SCRIPT="//assets.adobedtm.com/b92787824f2e0e9b68dc2e993f9bd995339fe417/satelliteLib-7ba51e58dc61bcb0e9311aadd02a0108ab24cc6c.js"

docs/conf.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2023-2024, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# Copyright 2023-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -35,9 +35,12 @@
 # -- Path setup --------------------------------------------------------------
 
 import json
+import logging
 import os
 import re
+import subprocess
 from datetime import date
+from logging.handlers import RotatingFileHandler
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -61,6 +64,45 @@
 # at the end of the file.
 # current_dir = os.getcwd()
 # os.chdir("docs")
+# -- Setup logger ------------------------------------------------------------
+
+
+def setup_logger(name, log_file, level=logging.INFO, max_bytes=1048576, backup_count=5):
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Prevent adding multiple handlers if the function is called multiple times
+    if not logger.handlers:
+        # Create handlers
+        file_handler = RotatingFileHandler(
+            log_file, maxBytes=max_bytes, backupCount=backup_count
+        )
+        console_handler = logging.StreamHandler()
+
+        # Set the logging level for handlers
+        file_handler.setLevel(level)
+        console_handler.setLevel(level)
+
+        # Create a logging format
+        BLUE = "\033[94m"
+        RESET = "\033[0m"
+        formatter = logging.Formatter(
+            f"{BLUE}%(asctime)s - %(name)s - %(levelname)s - {RESET}%(message)s"
+        )
+        file_handler.setFormatter(formatter)
+        console_handler.setFormatter(formatter)
+
+        # Add handlers to the logger
+        logger.addHandler(file_handler)
+        logger.addHandler(console_handler)
+    return logger
+
+
+logger = setup_logger(
+    os.path.basename(__file__),
+    os.environ.get("TRITON_SERVER_DOCS_LOG_FILE", "/tmp/docs.log"),
+)
+logger.info(f"Defined logger for {os.path.basename(__file__)}")
 
 # -- Project information -----------------------------------------------------
 
@@ -70,14 +112,19 @@
 
 # Get the version of Triton this is building.
 version_long = "0.0.0"
+logger.info(f"Getting version from ../TRITON_VERSION")
 with open("../TRITON_VERSION") as f:
     version_long = f.readline()
     version_long = version_long.strip()
+    logger.info(f"Version: {version_long}")
+
 
 version_short = re.match(r"^[\d]+\.[\d]+\.[\d]+", version_long).group(0)
+logger.info(f"Version short: {version_short}")
 version_short_split = version_short.split(".")
+logger.info(f"Version short split: {version_short_split}")
 one_before = f"{version_short_split[0]}.{int(version_short_split[1]) - 1}.{version_short_split[2]}"
-
+logger.info(f"One before: {one_before}")
 
 # maintain left-side bar toctrees in `contents` file
 # so it doesn't show up needlessly in the index page
@@ -180,7 +227,7 @@
         "json_url": "https://docs.nvidia.com/deeplearning/triton-inference-server/user-guide/docs/_static/switcher.json",
         "version_match": one_before if "dev" in version_long else version_short,
     },
-    "navbar_start": ["navbar-logo", "version-switcher"],
+    # "navbar_start": ["navbar-logo", "version-switcher"],
     "primary_sidebar_end": [],
 }
 
@@ -194,6 +241,8 @@
     }
 )
 
+logger.info(f"html_theme_options: {html_theme_options}")
+
 deploy_ngc_org = "nvidia"
 deploy_ngc_team = "triton"
 myst_substitutions = {
@@ -203,6 +252,8 @@
     else deploy_ngc_org,
 }
 
+logger.info(f"myst_substitutions: {myst_substitutions}")
+
 
 def ultimateReplace(app, docname, source):
     result = source[0]
@@ -219,6 +270,7 @@ def ultimateReplace(app, docname, source):
     if deploy_ngc_team
     else deploy_ngc_org,
 }
+logger.info(f"ultimate_replacements: {ultimate_replacements}")
 
 # bibtex_bibfiles = ["references.bib"]
 # To test that style looks good with common bibtex config
@@ -233,25 +285,30 @@ def ultimateReplace(app, docname, source):
 # SETUP SWITCHER
 ###############################
 switcher_path = os.path.join(html_static_path[0], "switcher.json")
+logger.info(f"switcher_path: {switcher_path}")
 versions = []
 # Triton 2 releases
-correction = -1 if "dev" in version_long else 0
-upper_bound = version_short.split(".")[1]
-for i in range(2, int(version_short.split(".")[1]) + correction):
-    versions.append((f"2.{i}.0", f"triton-inference-server-2{i}0"))
-
-# Triton 1 releases
-for i in range(0, 15):
-    versions.append((f"1.{i}.0", f"tensorrt_inference_server_1{i}0"))
-
-# Triton Beta Releases
-for i in range(1, 11):
-    versions.append((f"0.{i}.0_beta", f"inference_server_0{i}0_beta"))
+# correction = -1 if "dev" in version_long else 0
+# upper_bound = version_short.split(".")[1]
+# for i in range(2, int(version_short.split(".")[1]) + correction):
+#     versions.append((f"2.{i}.0", f"triton-inference-server-2{i}0"))
+# logger.info(f"Found Triton 2 releases: {versions}")
+
+# Obtain Triton Server Release Tags.
+tags = subprocess.run(["git", "tag", "--list", "v*"], capture_output=True, text=True)
+tags_list = sorted(tags.stdout.strip().splitlines(), key=Version, reverse=True)
+logger.info(f"Found source tags: {tags_list}")
+
+for v in tags_list:
+    versions.append(
+        (
+            v.replace("v", ""),
+            f"triton-inference-server-{v.replace('v', '').replace('.', '')}",
+        )
+    )
 
-# Patch releases
-# Add here.
+logger.info(f"Defined dictionary of versions: {versions}")
 
-versions = sorted(versions, key=lambda v: Version(v[0]), reverse=True)
 
 # Build switcher data
 json_data = []
@@ -263,6 +320,7 @@ def ultimateReplace(app, docname, source):
             "url": f"https://docs.nvidia.com/deeplearning/triton-inference-server/archives/{v[1]}/user-guide/docs",
         }
     )
+
 if "dev" in version_long:
     json_data.insert(
         0,
@@ -284,6 +342,7 @@ def ultimateReplace(app, docname, source):
 
 # Trim to last N releases.
 json_data = json_data[0:12]
+logger.info(f"Trimmed to last 12 release...")
 
 json_data.append(
     {
@@ -293,19 +352,22 @@ def ultimateReplace(app, docname, source):
     }
 )
 
-# validate the links
 for i, d in enumerate(json_data):
+    logger.info(f"Validating link: {d['url']}")
     h = httplib2.Http()
     resp = h.request(d["url"], "HEAD")
     if int(resp[0]["status"]) >= 400:
         print(d["url"], "NOK", resp[0]["status"])
-        exit(1)
+        # exit(1)
 
-# Write switcher data to file
+logger.info(f"Writing switcher data to file: {switcher_path}")
 with open(switcher_path, "w") as f:
     json.dump(json_data, f, ensure_ascii=False, indent=4)
 
 
+logger.info("Configuration completed...")
+
+
 def setup(app):
     app.add_config_value("ultimate_replacements", {}, True)
     app.connect("source-read", ultimateReplace)