[chore] Automate creation of release notes toc (#1155)

* [chore] Automate creation of release notes toc

* Add missing things

* Improve TOCs

* Rename function

* Fix toctree sorting

* Address comments in PR

Author: mdboom

cuda_bindings/docs/source/conf.py

@@ -9,13 +9,11 @@
 
 # -- Path setup --------------------------------------------------------------
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
+import sys
+from pathlib import Path
 
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, str((Path(__file__).parents[3] / "cuda_python" / "docs" / "exts").absolute()))
 
 
 # -- Project information -----------------------------------------------------
@@ -41,6 +39,7 @@
     "myst_nb",
     "enum_tools.autoenum",
     "sphinx_copybutton",
+    "release_toc",
 ]
 
 nb_execution_mode = "off"

cuda_bindings/docs/source/release.rst

@@ -6,38 +6,6 @@ Release Notes
 
 .. toctree::
    :maxdepth: 3
+   :glob:
 
-   13.0.3 <release/13.0.3-notes.rst>
-   13.0.2 <release/13.0.2-notes.rst>
-   13.0.1 <release/13.0.1-notes.rst>
-   13.0.0 <release/13.0.0-notes.rst>
-   12.9.4 <release/12.9.4-notes.rst>
-   12.9.3 <release/12.9.3-notes.rst>
-   12.9.2 <release/12.9.2-notes.rst>
-   12.9.1 <release/12.9.1-notes.rst>
-   12.9.0 <release/12.9.0-notes.rst>
-   12.8.0 <release/12.8.0-notes.rst>
-   12.6.2 <release/12.6.2-notes.rst>
-   12.6.1 <release/12.6.1-notes.rst>
-   12.6.0 <release/12.6.0-notes.rst>
-   12.5.0 <release/12.5.0-notes.rst>
-   12.4.0 <release/12.4.0-notes.rst>
-   12.3.0 <release/12.3.0-notes.rst>
-   12.2.1 <release/12.2.1-notes.rst>
-   12.2.0 <release/12.2.0-notes.rst>
-   12.1.0 <release/12.1.0-notes.rst>
-   12.0.0 <release/12.0.0-notes.rst>
-   11.8.7 <release/11.8.7-notes.rst>
-   11.8.6 <release/11.8.6-notes.rst>
-   11.8.5 <release/11.8.5-notes.rst>
-   11.8.4 <release/11.8.4-notes.rst>
-   11.8.3 <release/11.8.3-notes.rst>
-   11.8.2 <release/11.8.2-notes.rst>
-   11.8.1 <release/11.8.1-notes.rst>
-   11.8.0 <release/11.8.0-notes.rst>
-   11.7.1 <release/11.7.1-notes.rst>
-   11.7.0 <release/11.7.0-notes.rst>
-   11.6.1 <release/11.6.1-notes.rst>
-   11.6.0 <release/11.6.0-notes.rst>
-   11.5.0 <release/11.5.0-notes.rst>
-   11.4.0 <release/11.4.0-notes.rst>
+   release/*[0-9]-notes

cuda_core/docs/source/conf.py

@@ -9,12 +9,11 @@
 
 # -- Path setup --------------------------------------------------------------
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
+import sys
+from pathlib import Path
 
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, str((Path(__file__).parents[3] / "cuda_python" / "docs" / "exts").absolute()))
 
 
 # -- Project information -----------------------------------------------------
@@ -41,6 +40,7 @@
     "enum_tools.autoenum",
     "sphinx_copybutton",
     "sphinx_toolbox.more_autodoc.autoprotocol",
+    "release_toc",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

cuda_core/docs/source/release.rst

@@ -6,11 +6,6 @@ Release Notes
 
 .. toctree::
    :maxdepth: 3
+   :glob:
 
-   0.4.0 <release/0.4.0-notes>
-   0.3.2 <release/0.3.2-notes>
-   0.3.1 <release/0.3.1-notes>
-   0.3.0 <release/0.3.0-notes>
-   0.2.0 <release/0.2.0-notes>
-   0.1.1 <release/0.1.1-notes>
-   0.1.0 <release/0.1.0-notes>
+   release/*[0-9]-notes

cuda_pathfinder/docs/source/conf.py

@@ -9,13 +9,11 @@
 
 # -- Path setup --------------------------------------------------------------
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
+import sys
+from pathlib import Path
 
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, str((Path(__file__).parents[3] / "cuda_python" / "docs" / "exts").absolute()))
 
 
 # -- Project information -----------------------------------------------------
@@ -41,6 +39,7 @@
     "myst_nb",
     "enum_tools.autoenum",
     "sphinx_copybutton",
+    "release_toc",
 ]
 
 nb_execution_mode = "off"

cuda_pathfinder/docs/source/release.rst

@@ -6,12 +6,6 @@ Release Notes
 
 .. toctree::
    :maxdepth: 3
+   :glob:
 
-   1.3.1 <release/1.3.1-notes>
-   1.3.0 <release/1.3.0-notes>
-   1.2.3 <release/1.2.3-notes>
-   1.2.2 <release/1.2.2-notes>
-   1.2.1 <release/1.2.1-notes>
-   1.2.0 <release/1.2.0-notes>
-   1.1.0 <release/1.1.0-notes>
-   1.0.0 <release/1.0.0-notes>
+   release/*[0-9]-notes

cuda_python/docs/exts/release_toc.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
+
+from pathlib import Path
+
+from packaging.version import Version
+from sphinx.directives.other import TocTree
+
+
+class TocTreeSorted(TocTree):
+    """A toctree directive that sorts entries by version."""
+
+    def parse_content(self, toctree):
+        super().parse_content(toctree)
+
+        if not toctree["glob"]:
+            return
+
+        entries = toctree.get("entries", [])
+        if not entries:
+            return
+
+        entries = [(Version(Path(x[1]).name.removesuffix("-notes")), x[1]) for x in entries]
+        entries.sort(key=lambda x: x[0], reverse=True)
+        entries = [(str(x[0]), x[1]) for x in entries]
+        toctree["entries"] = entries
+
+
+def setup(app):
+    app.add_directive("toctree", TocTreeSorted, override=True)

cuda_python/docs/source/conf.py

@@ -9,13 +9,11 @@
 
 # -- Path setup --------------------------------------------------------------
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
+import sys
+from pathlib import Path
 
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, str((Path(__file__).parents[1] / "exts").absolute()))
 
 
 # -- Project information -----------------------------------------------------
@@ -38,6 +36,7 @@
     "sphinx.ext.napoleon",
     "myst_nb",
     "enum_tools.autoenum",
+    "release_toc",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

cuda_python/docs/source/release.rst

@@ -6,18 +6,6 @@ Release Notes
 
 .. toctree::
    :maxdepth: 3
+   :glob:
 
-   13.0.3 <release/13.0.3-notes.rst>
-   13.0.2 <release/13.0.2-notes.rst>
-   13.0.1 <release/13.0.1-notes.rst>
-   13.0.0 <release/13.0.0-notes.rst>
-   12.9.4 <release/12.9.4-notes.rst>
-   12.9.3 <release/12.9.3-notes.rst>
-   12.9.2 <release/12.9.2-notes.rst>
-   12.9.1 <release/12.9.1-notes.rst>
-   12.9.0 <release/12.9.0-notes.rst>
-   12.8.0 <release/12.8.0-notes.rst>
-   12.6.2 <release/12.6.2-notes.rst>
-   12.6.1 <release/12.6.1-notes.rst>
-   11.8.7 <release/11.8.7-notes.rst>
-   11.8.6 <release/11.8.6-notes.rst>
+   release/*[0-9]-notes