Merge pull request #2276 from IntelPython/enable-versioned-documentation

Enable versioned documentation

Author: ndgrigorian

.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 || 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' }}

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.

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. #}
-  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
-    <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="fa fa-book"> Other versions</span>
-      v: {{ current_version }}
-      <span class="fa fa-caret-down"></span>
-    </span>
-    <div class="rst-other-versions">
-      {% if versions|length >= 1 %}
-      <dl>
-        <dt>{{ _('Versions') }}</dt>
-        {% for slug, url in versions %}
-          {% if slug == current_version %} <strong> {% endif %}
-          <dd><a href="{{ url }}">{{ slug }}</a></dd>
-          {% if slug == current_version %} </strong> {% endif %}
-        {% endfor %}
-      </dl>
-      {% endif %}
-    </div>
-  </div>
+{% if display_lower_left %}
+<div class="sidebar-versions" style="padding: 1em; border-top: 1px solid var (--color-sidebar-brand-text);">
+  <strong>Docs Version</strong>
+  <select onchange="window.location.href=this.value" style="width: 100%; margin-top: 0.5em; padding: 0.25em;">
+    {% for slug, url in versions %}
+    <option value="{{ url }}" {% if slug==current_version %}selected{% endif %}>
+      {{ slug }}
+    </option>
+    {% endfor %}
+  </select>
+</div>
 {% endif %}

docs/doc_sources/conf.py.in

@@ -137,15 +137,18 @@ 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
     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:
@@ -160,3 +163,19 @@ if generate_multiversion == "ON":
         html_context["versions"].append(
             (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",
+            "sidebar/brand.html",
+            "sidebar/search.html",
+            "versions.html",
+            "sidebar/navigation.html",
+            "sidebar/ethical-ads.html",
+            "sidebar/scroll-end.html",
+        ]
+    }

docs/doc_versions.txt

@@ -1,4 +1,3 @@
-0.8.0
-0.7.0
-0.6.1
 latest
+0.21.1
+0.21.0

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()