From 5d2439e9677d6b0e45efbd3aafe1ea57ad31aad0 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 9 Apr 2026 18:35:41 -0700 Subject: [PATCH 1/9] change doc versions listed in doc_versions.txt --- docs/doc_versions.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/doc_versions.txt b/docs/doc_versions.txt index c0bd798a2c..230b7398e9 100644 --- a/docs/doc_versions.txt +++ b/docs/doc_versions.txt @@ -1,4 +1,3 @@ -0.8.0 -0.7.0 -0.6.1 +0.21.1 +0.21.0 latest From 2ec6aa2dccc35e86a3dd30dc980b1d00c50b81ce Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 9 Apr 2026 19:48:24 -0700 Subject: [PATCH 2/9] add --multiversion option to gen_docs.py and use in doc generation --- .github/workflows/generate-docs.yml | 2 +- scripts/gen_docs.py | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index ea0a3afde7..b476a557e7 100644 --- a/.github/workflows/generate-docs.yml +++ b/.github/workflows/generate-docs.yml @@ -75,7 +75,7 @@ jobs: source /opt/intel/oneapi/setvars.sh wget https://github.com/vovkos/doxyrest/releases/download/doxyrest-2.1.2/doxyrest-2.1.2-linux-amd64.tar.xz tar xf doxyrest-2.1.2-linux-amd64.tar.xz - python scripts/gen_docs.py --doxyrest-root=`pwd`/doxyrest-2.1.2-linux-amd64 --verbose || exit 1 + python scripts/gen_docs.py --doxyrest-root=`pwd`/doxyrest-2.1.2-linux-amd64 --verbose --multiversion || exit 1 python -c "import dpctl; print(dpctl.__version__)" || exit 1 pushd "$(find _skbuild -name cmake-build)" || exit 1 cmake --build . --target Sphinx || exit 1 diff --git a/scripts/gen_docs.py b/scripts/gen_docs.py index 548a664e5b..235ec8f0e6 100644 --- a/scripts/gen_docs.py +++ b/scripts/gen_docs.py @@ -95,6 +95,12 @@ def parse_args(): ), ) + p.add_argument( + "--multiversion", + action="store_true", + help="Enable multiversion sidebar links in docs (default: False)", + ) + p.add_argument( "--clean", action="store_true", @@ -137,6 +143,9 @@ def main(): cmake_args += ["-DDPCTL_ENABLE_DOXYREST=ON"] cmake_args += [f"-DDoxyrest_DIR={args.doxyrest_root}"] + if args.multiversion: + cmake_args += ["-DDPCTL_USE_MULTIVERSION_TEMPLATE=ON"] + log_cmake_args(cmake_args, "gen_docs") env = os.environ.copy() From 2dab64c34d5606b0476c386e2ab87beb0c6e5258 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 9 Apr 2026 20:40:00 -0700 Subject: [PATCH 3/9] add logic to find doc_versions.txt --- docs/doc_sources/conf.py.in | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/doc_sources/conf.py.in b/docs/doc_sources/conf.py.in index 97cdbbe0df..e5bef5d542 100644 --- a/docs/doc_sources/conf.py.in +++ b/docs/doc_sources/conf.py.in @@ -143,9 +143,12 @@ if generate_multiversion == "ON": # POPULATE LINKS TO OTHER VERSIONS html_context["versions"] = list() - # Populate the list of documented versions from the doc_versions.tx + # Populate the list of documented versions from the doc_versions.txt versions = [] - with open("doc_versions.txt", "r") as doc_versions: + + conf_dir = os.path.dirname(os.path.abspath(__file__)) + versions_file = os.path.join(conf_dir, "..", "doc_versions.txt") + with open(versions_file, "r") as doc_versions: while True: version = doc_versions.readline().strip() if not version: From 62d166ef5abe49950c69bf3a299e5a7c8436408c Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 9 Apr 2026 22:40:50 -0700 Subject: [PATCH 4/9] add custom sidebar element for versions --- docs/doc_sources/_templates/versions.html | 32 ++++++++--------------- docs/doc_sources/conf.py.in | 12 +++++++++ 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/doc_sources/_templates/versions.html b/docs/doc_sources/_templates/versions.html index 623bf289d5..a2df1513c1 100644 --- a/docs/doc_sources/_templates/versions.html +++ b/docs/doc_sources/_templates/versions.html @@ -1,22 +1,12 @@ -{% if READTHEDOCS or display_lower_left %} -{# Add rst-badge after rst-versions for small badge style. #} -
- - Other versions - v: {{ current_version }} - - -
- {% if versions|length >= 1 %} -
-
{{ _('Versions') }}
- {% for slug, url in versions %} - {% if slug == current_version %} {% endif %} -
{{ slug }}
- {% if slug == current_version %} {% endif %} - {% endfor %} -
- {% endif %} -
-
+{% if display_lower_left %} +
+ Docs Version + +
{% endif %} diff --git a/docs/doc_sources/conf.py.in b/docs/doc_sources/conf.py.in index e5bef5d542..c9b7fa90f0 100644 --- a/docs/doc_sources/conf.py.in +++ b/docs/doc_sources/conf.py.in @@ -163,3 +163,15 @@ if generate_multiversion == "ON": html_context["versions"].append( (version, DOC_SITE_NAME + version + "/index.html") ) + + html_sidebars = { + "**": [ + "sidebar/scroll-start.html", + "sidebar/brand.html", + "sidebar/search.html", + "versions.html", + "sidebar/navigation.html", + "sidebar/ethical-ads.html", + "sidebar/scroll-end.html", + ] + } From 56294eafed8ce4e68801cd1dc02b2972247c7d6e Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 9 Apr 2026 23:24:51 -0700 Subject: [PATCH 5/9] if docs version can't be determined, default to displaying latest --- docs/doc_sources/conf.py.in | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/doc_sources/conf.py.in b/docs/doc_sources/conf.py.in index c9b7fa90f0..49e129d455 100644 --- a/docs/doc_sources/conf.py.in +++ b/docs/doc_sources/conf.py.in @@ -164,6 +164,10 @@ if generate_multiversion == "ON": (version, DOC_SITE_NAME + version + "/index.html") ) + if html_context["current_version"] not in versions: + html_context["current_version"] = "latest" + + # override furo sidebar when multiversion is on to add the version dropdown html_sidebars = { "**": [ "sidebar/scroll-start.html", From 9f5ac602124ceeeca561042ad721273f2b7effde Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 10:45:42 -0700 Subject: [PATCH 6/9] add gh-2276 to changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 426269eb1e..2183163531 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Maintenance +* Enabled multiversion documentation for `dpctl` using a custom drop-down for version selection and a `--multiversion` option for documentation build helper script [gh-2276](https://github.com/IntelPython/dpctl/pull/2276) + ## [0.21.1] - Nov. 29, 2025 This release is made to distribute `dpctl` for Python 3.14. Only the non-free-threaded version of Python is supported as of this release. From 3e9a41f0cfa21edadbf8bc5713fd74944c54e6a5 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 14:22:56 -0700 Subject: [PATCH 7/9] move latest to top of doc_versions --- docs/doc_versions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doc_versions.txt b/docs/doc_versions.txt index 230b7398e9..e448b42499 100644 --- a/docs/doc_versions.txt +++ b/docs/doc_versions.txt @@ -1,3 +1,3 @@ +latest 0.21.1 0.21.0 -latest From a2ffa9b80161f92918663f222585f9b764e9ab82 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 14:49:09 -0700 Subject: [PATCH 8/9] use release for multiversioned documentation current_version context this strips hash off of version --- docs/doc_sources/conf.py.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doc_sources/conf.py.in b/docs/doc_sources/conf.py.in index 49e129d455..dbafbb774a 100644 --- a/docs/doc_sources/conf.py.in +++ b/docs/doc_sources/conf.py.in @@ -137,7 +137,7 @@ if generate_multiversion == "ON": html_context = dict() html_context["display_lower_left"] = True templates_path = ["_templates"] - html_context["current_version"] = version + html_context["current_version"] = release html_context["version"] = version # POPULATE LINKS TO OTHER VERSIONS From c24629425e6818817b08d9b6c8930b924c9b4656 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 15:28:11 -0700 Subject: [PATCH 9/9] drop unnecessary step in generate-docs workflow --- .github/workflows/generate-docs.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index b476a557e7..5748ed7a75 100644 --- a/.github/workflows/generate-docs.yml +++ b/.github/workflows/generate-docs.yml @@ -75,13 +75,10 @@ jobs: source /opt/intel/oneapi/setvars.sh wget https://github.com/vovkos/doxyrest/releases/download/doxyrest-2.1.2/doxyrest-2.1.2-linux-amd64.tar.xz tar xf doxyrest-2.1.2-linux-amd64.tar.xz - python scripts/gen_docs.py --doxyrest-root=`pwd`/doxyrest-2.1.2-linux-amd64 --verbose --multiversion || exit 1 + python scripts/gen_docs.py --doxyrest-root=`pwd`/doxyrest-2.1.2-linux-amd64 --verbose --multiversion --clean || exit 1 python -c "import dpctl; print(dpctl.__version__)" || exit 1 - pushd "$(find _skbuild -name cmake-build)" || exit 1 - cmake --build . --target Sphinx || exit 1 - mv ../cmake-install/docs/docs ~/docs + mv "$(find _skbuild -type d -path "*/cmake-install/docs/docs" | head -n 1)" ~/docs git clean -dfx - popd git reset --hard - name: Publish docs if: ${{ !github.event.pull_request && github.ref == 'refs/heads/master' }}