From d513f0f71431466c9755f52e8948871f4f28b644 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Oct 2025 12:32:52 -0400 Subject: [PATCH 1/6] [chore] Automate creation of release notes toc --- cuda_bindings/docs/source/conf.py | 9 ++++--- cuda_bindings/docs/source/release.rst | 34 ++------------------------- cuda_core/docs/source/conf.py | 8 +++---- cuda_core/docs/source/release.rst | 9 ++----- cuda_pathfinder/docs/source/conf.py | 9 ++++--- cuda_python/docs/exts/release_toc.py | 19 +++++++++++++++ cuda_python/docs/source/conf.py | 8 +++---- cuda_python/docs/source/release.rst | 12 ++-------- 8 files changed, 40 insertions(+), 68 deletions(-) create mode 100644 cuda_python/docs/exts/release_toc.py diff --git a/cuda_bindings/docs/source/conf.py b/cuda_bindings/docs/source/conf.py index 93427d3631..b05ff9d0de 100644 --- a/cuda_bindings/docs/source/conf.py +++ b/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" diff --git a/cuda_bindings/docs/source/release.rst b/cuda_bindings/docs/source/release.rst index 66a74c497a..f9a24a36b3 100644 --- a/cuda_bindings/docs/source/release.rst +++ b/cuda_bindings/docs/source/release.rst @@ -6,36 +6,6 @@ Release Notes .. toctree:: :maxdepth: 3 + :glob: - 13.0.2 - 13.0.1 - 13.0.0 - 12.9.3 - 12.9.2 - 12.9.1 - 12.9.0 - 12.8.0 - 12.6.2 - 12.6.1 - 12.6.0 - 12.5.0 - 12.4.0 - 12.3.0 - 12.2.1 - 12.2.0 - 12.1.0 - 12.0.0 - 11.8.7 - 11.8.6 - 11.8.5 - 11.8.4 - 11.8.3 - 11.8.2 - 11.8.1 - 11.8.0 - 11.7.1 - 11.7.0 - 11.6.1 - 11.6.0 - 11.5.0 - 11.4.0 + release/*[0-9]-notes diff --git a/cuda_core/docs/source/conf.py b/cuda_core/docs/source/conf.py index c172d0995f..e735918c41 100644 --- a/cuda_core/docs/source/conf.py +++ b/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. diff --git a/cuda_core/docs/source/release.rst b/cuda_core/docs/source/release.rst index 8be38864c5..601f3bf220 100644 --- a/cuda_core/docs/source/release.rst +++ b/cuda_core/docs/source/release.rst @@ -6,11 +6,6 @@ Release Notes .. toctree:: :maxdepth: 3 + :glob: - 0.4.0 - 0.3.2 - 0.3.1 - 0.3.0 - 0.2.0 - 0.1.1 - 0.1.0 + release/*[0-9]-notes diff --git a/cuda_pathfinder/docs/source/conf.py b/cuda_pathfinder/docs/source/conf.py index 1ef35cc18b..151e86b284 100644 --- a/cuda_pathfinder/docs/source/conf.py +++ b/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" diff --git a/cuda_python/docs/exts/release_toc.py b/cuda_python/docs/exts/release_toc.py new file mode 100644 index 0000000000..8cf7e9ea27 --- /dev/null +++ b/cuda_python/docs/exts/release_toc.py @@ -0,0 +1,19 @@ +# 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 + + +def reverse_toctree(app, doctree, docname): + """Sort the entries in a release toctree in by version.""" + if docname == "release": + for node in doctree.traverse(): + if node.tagname == "toctree": + node["entries"].sort(key=lambda x: Version(Path(x[1]).name.removesuffix("-notes")), reverse=True) + break + + +def setup(app): + app.connect("doctree-resolved", reverse_toctree) diff --git a/cuda_python/docs/source/conf.py b/cuda_python/docs/source/conf.py index b8c15c6e66..af860fa056 100644 --- a/cuda_python/docs/source/conf.py +++ b/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 ----------------------------------------------------- diff --git a/cuda_python/docs/source/release.rst b/cuda_python/docs/source/release.rst index 9e7a66a522..f9a24a36b3 100644 --- a/cuda_python/docs/source/release.rst +++ b/cuda_python/docs/source/release.rst @@ -6,14 +6,6 @@ Release Notes .. toctree:: :maxdepth: 3 + :glob: - 13.0.1 - 13.0.0 - 12.9.2 - 12.9.1 - 12.9.0 - 12.8.0 - 12.6.2 - 12.6.1 - 11.8.7 - 11.8.6 + release/*[0-9]-notes From a1fa8a3d700e3a08219f6c2e8c286228c7540bc5 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Oct 2025 12:36:10 -0400 Subject: [PATCH 2/6] Add missing things --- cuda_pathfinder/docs/source/release.rst | 10 ++-------- cuda_python/docs/source/conf.py | 1 + 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/cuda_pathfinder/docs/source/release.rst b/cuda_pathfinder/docs/source/release.rst index cd837b57ff..601f3bf220 100644 --- a/cuda_pathfinder/docs/source/release.rst +++ b/cuda_pathfinder/docs/source/release.rst @@ -6,12 +6,6 @@ Release Notes .. toctree:: :maxdepth: 3 + :glob: - 1.3.1 - 1.3.0 - 1.2.3 - 1.2.2 - 1.2.1 - 1.2.0 - 1.1.0 - 1.0.0 + release/*[0-9]-notes diff --git a/cuda_python/docs/source/conf.py b/cuda_python/docs/source/conf.py index af860fa056..8018a91108 100644 --- a/cuda_python/docs/source/conf.py +++ b/cuda_python/docs/source/conf.py @@ -36,6 +36,7 @@ "sphinx.ext.napoleon", "myst_nb", "enum_tools.autoenum", + "release_toc", ] # Add any paths that contain templates here, relative to this directory. From 163c6243b7dd800f045d6af4b78926ad19a232af Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Mon, 20 Oct 2025 14:53:59 -0400 Subject: [PATCH 3/6] Improve TOCs --- cuda_python/docs/exts/release_toc.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cuda_python/docs/exts/release_toc.py b/cuda_python/docs/exts/release_toc.py index 8cf7e9ea27..51cfbff83b 100644 --- a/cuda_python/docs/exts/release_toc.py +++ b/cuda_python/docs/exts/release_toc.py @@ -11,7 +11,8 @@ def reverse_toctree(app, doctree, docname): if docname == "release": for node in doctree.traverse(): if node.tagname == "toctree": - node["entries"].sort(key=lambda x: Version(Path(x[1]).name.removesuffix("-notes")), reverse=True) + node["entries"] = [(Version(Path(x[1]).name.removesuffix("-notes")), x[1]) for x in node["entries"]] + node["entries"].sort(key=lambda x: x[0], reverse=True) break From 42e5cc883f7a235db2e08ad85af60948ff07cae6 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Mon, 20 Oct 2025 15:53:14 -0400 Subject: [PATCH 4/6] Rename function --- cuda_python/docs/exts/release_toc.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cuda_python/docs/exts/release_toc.py b/cuda_python/docs/exts/release_toc.py index 51cfbff83b..0b76c3cdee 100644 --- a/cuda_python/docs/exts/release_toc.py +++ b/cuda_python/docs/exts/release_toc.py @@ -6,7 +6,7 @@ from packaging.version import Version -def reverse_toctree(app, doctree, docname): +def sort_release_toctree(app, doctree, docname): """Sort the entries in a release toctree in by version.""" if docname == "release": for node in doctree.traverse(): @@ -17,4 +17,4 @@ def reverse_toctree(app, doctree, docname): def setup(app): - app.connect("doctree-resolved", reverse_toctree) + app.connect("doctree-resolved", sort_release_toctree) From 596ffba75d296a33db9ccc2d92aca183c8b46909 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Mon, 20 Oct 2025 16:44:06 -0400 Subject: [PATCH 5/6] Fix toctree sorting --- cuda_python/docs/exts/release_toc.py | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/cuda_python/docs/exts/release_toc.py b/cuda_python/docs/exts/release_toc.py index 0b76c3cdee..f1bc91f27e 100644 --- a/cuda_python/docs/exts/release_toc.py +++ b/cuda_python/docs/exts/release_toc.py @@ -4,17 +4,24 @@ from pathlib import Path from packaging.version import Version +from sphinx.directives.other import TocTree -def sort_release_toctree(app, doctree, docname): - """Sort the entries in a release toctree in by version.""" - if docname == "release": - for node in doctree.traverse(): - if node.tagname == "toctree": - node["entries"] = [(Version(Path(x[1]).name.removesuffix("-notes")), x[1]) for x in node["entries"]] - node["entries"].sort(key=lambda x: x[0], reverse=True) - break +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 + + toctree["entries"] = [ + (Version(Path(x[1]).name.removesuffix("-notes")), x[1]) for x in toctree.get("entries", []) + ] + toctree["entries"].sort(key=lambda x: x[0], reverse=True) + toctree["entries"] = [(str(x[0]), x[1]) for x in toctree["entries"]] def setup(app): - app.connect("doctree-resolved", sort_release_toctree) + app.add_directive("toctree", TocTreeSorted, override=True) From 705890b191a87113bb018a78d49dee8552df6a4f Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 21 Oct 2025 08:44:59 -0400 Subject: [PATCH 6/6] Address comments in PR --- cuda_python/docs/exts/release_toc.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/cuda_python/docs/exts/release_toc.py b/cuda_python/docs/exts/release_toc.py index f1bc91f27e..11abc3b115 100644 --- a/cuda_python/docs/exts/release_toc.py +++ b/cuda_python/docs/exts/release_toc.py @@ -16,11 +16,14 @@ def parse_content(self, toctree): if not toctree["glob"]: return - toctree["entries"] = [ - (Version(Path(x[1]).name.removesuffix("-notes")), x[1]) for x in toctree.get("entries", []) - ] - toctree["entries"].sort(key=lambda x: x[0], reverse=True) - toctree["entries"] = [(str(x[0]), x[1]) for x in toctree["entries"]] + 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):