Version support and automatic CI build

.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: publish
+'on':
+  push:
+    branches:
+      ktp-docs-ci
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: install dependencies
+      run: |
+        sudo apt update
+        sudo apt install -y pandoc git
+        pip3 install -r requirements-doc.txt
+        pip3 install scikit-learn-intelex
+        cd doc
+        source set_version.sh
+        echo Generating version $DOC_VERSION
+    - name: build docs
+      run: |
+        cd doc
+        chmod +x build-doc.sh
+        ./build-doc.sh
+        mv _build/scikit-learn-intelex ../../output
+    - name: deploy docs
+      run: |
+        cd doc
+        source set_version.sh
+        cd ..
+        git fetch
+        git checkout -- doc/build-doc.sh
+        git checkout gh-pages
+        rm -rf $DOC_VERSION
+        mv -f ../output/$DOC_VERSION .
+        mv ../output/versions.json .
+        mv ../output/index.html .
+        rm -rf doc
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest HTML output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.GITHUB_TOKEN}}@github.com/${GITHUB_REPOSITORY}.git HEAD:gh-pages
+

doc/build-doc.sh

@@ -27,6 +27,13 @@ mkdir $SAMPLES_DIR
 cd ..
 rsync -a --exclude='doc/$SAMPLES_DIR/daal4py_data_science.ipynb' examples/notebooks/*.ipynb doc/$SAMPLES_DIR
 
-# build the documentation
 cd doc
-make html
+
+source ./set_version.sh
+export SPHINXPROJ=scikit-learn-intelex
+export BUILDDIR=_build
+export SOURCEDIR=sources
+
+sphinx-build -b html $SOURCEDIR $BUILDDIR/$SPHINXPROJ/$DOC_VERSION
+cp versions.json $BUILDDIR/$SPHINXPROJ
+echo "<meta http-equiv=\"refresh\" content=\"0; URL='/$SPHINXPROJ/$DOC_VERSION/'\" / >" >> $BUILDDIR/$SPHINXPROJ/index.html

doc/get_doc_version.py

@@ -0,0 +1,15 @@
+import subprocess
+import os
+
+def get_version():
+    major = ''
+    minor = ''
+    pip_output = subprocess.run(["pip","list"],capture_output=True,encoding='utf-8')
+    lines = pip_output.stdout.split("\n")
+    for line in lines:
+        if line.startswith("scikit-learn-intelex"):
+            version = line.split()[1].split(".")
+            major = version[0]
+            minor = version[1]
+
+    return major + "." + minor

doc/set_version.sh

@@ -0,0 +1,2 @@
+export DOC_VERSION=$(python -c "from get_doc_version import get_version; print(get_version())")
+

doc/sources/_static/style.css → doc/sources/_static/custom.css

@@ -121,3 +121,11 @@ div.quotation {
 
 a#wap_dns {display: none;}
 
+
+button#version-switcher-button {
+   background-color:  #2980b9;
+}
+
+div#version-switcher-dropdown {
+   display: inline;
+}

doc/sources/_static/version_switcher.js

@@ -0,0 +1,31 @@
+function load_versions(json){
+    var button = document.getElementById('version-switcher-button')
+    var container = document.getElementById('version-switcher-dropdown')
+    var loc = window.location.href;
+    var s = document.createElement('select');
+    s.style = "border-radius:5px;"
+    const versions = JSON.parse(json);
+    for (entry of versions){
+        var o = document.createElement('option');
+        var optionText = '';
+        if ('name' in entry){
+            optionText = entry.name;
+        }else{
+            optionText = entry.version;
+        }
+        o.value = entry.url;
+        if (current_version == entry.version){
+            o.selected = true;
+        }
+        o.innerHTML = optionText;
+        s.append(o);
+    }
+    s.addEventListener("change", ()=> {
+        var current_url = new URL(window.location.href);
+        var path = current_url.pathname;
+        //strip version from path
+        var page_path = path.substring(project_name.length+current_version.length+3);
+        window.location.href = s.value + page_path;
+    });
+    container.append(s);
+}

doc/sources/_templates/layout.html

@@ -2,6 +2,7 @@
 {% block extrahead %}
     <script defer type="text/javascript" src="https://www.intel.com/content/dam/www/global/wap/performance-config.js" ></script>
     <script type="text/javascript">
+        fetch("{{ switcher_url }}").then(response => response.text()).then(respText=> load_versions(respText));
         // Configure TMS settings
         var wapLocalCode = 'us-en'; // Dynamically set per localized site, see mapping table for values
         var wapSection = "scikit-learn"; // WAP team will give you a unique section for your site
@@ -15,3 +16,8 @@
       }
       </script>
 {% endblock %}
+
+{% block menu %}
+  {% include "versions.html" %}
+  {{ super() }}
+{% endblock %}

doc/sources/_templates/versions.html

@@ -0,0 +1,23 @@
+<div class="version-switcher__container dropdown">
+    <script>
+      current_version = "{{current_version}}"
+      project_name = "{{project_name}}"
+    </script>
+    <div id="version-switcher-button"
+      class="version-switcher__button"
+      data-bs-toggle="dropdown"
+      aria-haspopup="listbox"
+      aria-controls="version-switcher-dropdown"
+      aria-label="Version switcher list"
+      style="display:inline-block;padding-left:10px;padding-right:10px;"
+    >
+      Choose version  <!-- this text may get changed later by javascript -->
+      <span class="caret"></span>
+    </div>
+    <div id="version-switcher-dropdown"
+      class="version-switcher__menu dropdown-menu list-group-flush py-0"
+      role="listbox" aria-labelledby="{{ button_id }}">
+      <!-- dropdown will be populated by javascript on page load -->
+    </div>
+  </div>
+

doc/sources/conf.py

@@ -25,6 +25,8 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import json
+
 # 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.
@@ -34,17 +36,16 @@
 
 sys.path.insert(0, os.path.abspath("../"))
 
-
 # -- Project information -----------------------------------------------------
 
 project = "Intel(R) Extension for Scikit-learn*"
 copyright = "Intel"
 author = "Intel"
 
 # The short X.Y version
-version = "2025.0.0"
+version = os.environ.get('DOC_VERSION','')
 # The full version, including alpha/beta/rc tags
-release = "2025.0.0"
+release = version
 
 
 # -- General configuration ---------------------------------------------------
@@ -154,6 +155,11 @@
     "titles_only": False,
 }
 
+switcher_url = "/scikit-learn-intelex/versions.json"
+
+html_context = {"current_version": version,
+                "project_name": "scikit-learn-intelex",
+                "switcher_url": switcher_url}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -163,6 +169,7 @@
 
 def setup(app):
     app.add_css_file("custom.css")
+    app.add_js_file("version_switcher.js")
 
 
 # -- Options for HTMLHelp output ---------------------------------------------

doc/versions.json

@@ -0,0 +1,19 @@
+[
+    {
+        "name": "2025.0 (latest)",
+        "version": "2025.0",
+        "url": "/scikit-learn-intelex/2025.0/"
+    },
+    {
+        "version": "2024.6",
+        "url": "/scikit-learn-intelex/2024.6/"
+    },
+    {
+        "version": "2024.3",
+        "url": "/scikit-learn-intelex/2024.3/"
+    },
+    {
+        "version": "2023.2",
+        "url": "/scikit-learn-intelex/2023.2/"
+    }
+]