docs: pin version in links to external docs [1/n]

.actions/assistant.py

@@ -359,17 +359,19 @@ def copy_replace_imports(
 
 
 def create_mirror_package(source_dir: str, package_mapping: Dict[str, str]) -> None:
+    """Create a mirror package with adjusted imports."""
     # replace imports and copy the code
     mapping = package_mapping.copy()
     mapping.pop("lightning", None)  # pop this key to avoid replacing `lightning` to `lightning.lightning`
 
     mapping = {f"lightning.{sp}": sl for sp, sl in mapping.items()}
     for pkg_from, pkg_to in mapping.items():
+        source_imports, target_imports = zip(*package_mapping.items())
         copy_replace_imports(
             source_dir=os.path.join(source_dir, pkg_from.replace(".", os.sep)),
             # pytorch_lightning uses lightning_fabric, so we need to replace all imports for all directories
-            source_imports=mapping.keys(),
-            target_imports=mapping.values(),
+            source_imports=source_imports,
+            target_imports=target_imports,
             target_dir=os.path.join(source_dir, pkg_to.replace(".", os.sep)),
             lightning_by=pkg_from,
         )

.github/workflows/docs-build.yml

@@ -106,7 +106,9 @@ jobs:
 
       - name: Full build for deployment
         if: github.event_name != 'pull_request'
-        run: echo "DOCS_FETCH_ASSETS=1" >> $GITHUB_ENV
+        run: |
+          echo "DOCS_FETCH_ASSETS=1" >> $GITHUB_ENV
+          echo "PIN_RELEASE_VERSIONS=1" >> $GITHUB_ENV
       - name: Make ${{ matrix.target }}
         working-directory: ./docs/source-${{ matrix.pkg-name }}
         # allow failing link check and doctest if you run with dispatch

docs/source-pytorch/conf.py

@@ -14,13 +14,12 @@
 import glob
 import os
 import shutil
-import urllib.request
 import warnings
 from importlib.util import module_from_spec, spec_from_file_location
 from types import ModuleType
 
 import lai_sphinx_theme
-from lightning_utilities.docs import fetch_external_assets
+from lightning_utilities.docs import adjust_linked_external_docs, fetch_external_assets
 from lightning_utilities.docs.formatting import _transform_changelog
 
 import lightning
@@ -32,6 +31,7 @@
 _FAST_DOCS_DEV = int(os.getenv("FAST_DOCS_DEV", True))
 _COPY_NOTEBOOKS = int(os.getenv("DOCS_COPY_NOTEBOOKS", not _FAST_DOCS_DEV))
 _FETCH_S3_ASSETS = int(os.getenv("DOCS_FETCH_ASSETS", not _FAST_DOCS_DEV))
+_PIN_RELEASE_VERSIONS = int(os.getenv("PIN_RELEASE_VERSIONS", not _FAST_DOCS_DEV))
 
 # -----------------------
 # BUILD stuff
@@ -111,6 +111,23 @@ def _load_py_module(name: str, location: str) -> ModuleType:
     )
 
 
+if _PIN_RELEASE_VERSIONS:
+    adjust_linked_external_docs(
+        "https://numpy.org/doc/stable/", "https://numpy.org/doc/{numpy.__version__}/", _PATH_ROOT
+    )
+    adjust_linked_external_docs(
+        "https://pytorch.org/docs/stable/", "https://pytorch.org/docs/{torch.__version__}/", _PATH_ROOT
+    )
+    adjust_linked_external_docs(
+        "https://lightning.ai/docs/torchmetrics", "https://lightning.ai/docs/torchmetrics/v{torchmetrics.__version__}/", _PATH_ROOT, version_digits=3
+    )
+    adjust_linked_external_docs(
+        "https://lightning.ai/docs/fabric/stable/", "https://lightning.ai/docs/fabric/{lightning_fabric.__version__}/", _PATH_ROOT, version_digits=3
+    )
+    adjust_linked_external_docs(
+        "https://tensorboardx.readthedocs.io/en/stable/", "https://tensorboardx.readthedocs.io/en/v{tensorboard.__version__}/", _PATH_ROOT
+    )
+
 # -- Project information -----------------------------------------------------
 
 project = "PyTorch Lightning"
@@ -327,7 +344,7 @@ def _load_py_module(name: str, location: str) -> ModuleType:
     "torch": ("https://pytorch.org/docs/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "PIL": ("https://pillow.readthedocs.io/en/stable/", None),
-    "torchmetrics": ("https://torchmetrics.readthedocs.io/en/stable/", None),
+    "torchmetrics": ("https://lightning.ai/docs/torchmetrics/stable/", None),
     "lightning_habana": ("https://lightning-ai.github.io/lightning-Habana/", None),
     "tensorboardX": ("https://tensorboardx.readthedocs.io/en/stable/", None),
     # needed for referencing App from lightning scope

requirements/docs.txt

@@ -17,6 +17,9 @@ sphinx-rtd-dark-mode
 sphinxcontrib-video ==0.2.0
 jinja2 <3.2.0
 
-lightning-utilities >=0.9.0
+# lightning-utilities >=0.11.0
+# todo: until the release of 0.11.0, use the following line
+lightning-utilities @ https://github.com/Lightning-AI/utilities/archive/refs/heads/main.zip
 
+# installed from S3 location and fetched in advance
 lai-sphinx-theme