docs: pin version in links to external docs [1/n] (#19584)

* docs: ignore link to private repo
* lightning-utilities >=0.11.0, <0.12.0

---------

Co-authored-by: awaelchli <aedu.waelchli@gmail.com>

.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(*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/app/app.txt

@@ -6,7 +6,7 @@ fsspec[http] >=2022.5.0, <2023.11.0
 croniter >=1.3.0, <1.5.0  # strict; TODO: for now until we find something more robust.
 traitlets >=5.3.0, <5.12.0
 arrow >=1.2.0, <1.3.0
-lightning-utilities >=0.8.0, <0.11.0
+lightning-utilities >=0.8.0, <0.12.0
 beautifulsoup4 >=4.8.0, <4.13.0
 inquirer >=2.10.0, <3.2.0
 psutil <5.9.6

requirements/docs.txt

@@ -17,6 +17,7 @@ sphinx-rtd-dark-mode
 sphinxcontrib-video ==0.2.0
 jinja2 <3.2.0
 
-lightning-utilities >=0.9.0
+lightning-utilities >=0.11.0, <0.12.0
 
+# installed from S3 location and fetched in advance
 lai-sphinx-theme

requirements/fabric/base.txt

@@ -6,4 +6,4 @@ torch >=1.13.0, <=2.2.0
 fsspec[http] >=2022.5.0, <2023.11.0
 packaging >=20.0, <=23.1
 typing-extensions >=4.4.0, <4.10.0
-lightning-utilities >=0.8.0, <0.11.0
+lightning-utilities >=0.8.0, <0.12.0

requirements/fabric/examples.txt

@@ -3,4 +3,4 @@
 
 torchvision >=0.14.0, <0.18.0
 torchmetrics >=0.10.0, <1.3.0
-lightning-utilities >=0.8.0, <0.11.0
+lightning-utilities >=0.8.0, <0.12.0

requirements/pytorch/base.txt

@@ -9,4 +9,4 @@ fsspec[http] >=2022.5.0, <2023.11.0
 torchmetrics >=0.7.0, <1.3.0  # needed for using fixed compare_version
 packaging >=20.0, <=23.1
 typing-extensions >=4.4.0, <4.10.0
-lightning-utilities >=0.8.0, <0.11.0
+lightning-utilities >=0.8.0, <0.12.0

requirements/pytorch/examples.txt

@@ -6,4 +6,4 @@ torchvision >=0.14.0, <0.18.0
 gym[classic_control] >=0.17.0, <0.27.0
 ipython[all] <8.15.0
 torchmetrics >=0.10.0, <1.3.0
-lightning-utilities >=0.8.0, <0.11.0
+lightning-utilities >=0.8.0, <0.12.0