diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index ea0a3afde7..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 || 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' }} 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. 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 %} + {% endif %} diff --git a/docs/doc_sources/conf.py.in b/docs/doc_sources/conf.py.in index 97cdbbe0df..dbafbb774a 100644 --- a/docs/doc_sources/conf.py.in +++ b/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", + ] + } diff --git a/docs/doc_versions.txt b/docs/doc_versions.txt index c0bd798a2c..e448b42499 100644 --- a/docs/doc_versions.txt +++ b/docs/doc_versions.txt @@ -1,4 +1,3 @@ -0.8.0 -0.7.0 -0.6.1 latest +0.21.1 +0.21.0 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()