Version support and automatic CI build #2214
Conversation
Signed-off-by: Putnam, Kevin <[email protected]>
Signed-off-by: Putnam, Kevin <[email protected]>
Signed-off-by: Putnam, Kevin <[email protected]>
Signed-off-by: Putnam, Kevin <[email protected]>
intelkevinputnam
requested review from
maria-Petrova,
napetrov,
Alexsandruss,
samir-nasibli,
icfaust,
david-cortes-intel,
homksei,
ahuber21 and
ethanglaser
as code owners
|
@intelkevinputnam I'm seeing several misrendered things in the docs from your branch. For example: This is how it looks for me in a local build: |
| make html | ||
|
|
||
| source ./set_version.sh | ||
| export SPHINXPROJ=scikit-learn-intelex |
There was a problem hiding this comment.
We also have daal4py with docs under doc/daal4py.
| import subprocess | ||
| import os | ||
|
|
||
| def get_version(): |
There was a problem hiding this comment.
@icfaust Could you please look into whether this captures the version number correctly.
| background-color: #2980b9; | ||
| } | ||
|
|
||
| div#version-switcher-dropdown { |
There was a problem hiding this comment.
Question: if we have this line right here, do we still need to add a version selector in the conf.py file?
scikit-learn-intelex/doc/sources/conf.py
Line 146 in 54aa18b
I understand that version selector plugin is meant for ReadTheDocs, so don't know how it plays with these.
| # -- 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','') |
There was a problem hiding this comment.
How about changing the version to "latest" here when it doesn't find the env. variable?
| @@ -0,0 +1,19 @@ | |||
| [ | |||
| { | |||
| "name": "2025.0 (latest)", | |||
There was a problem hiding this comment.
Could we make this file auto-generated from the releases that we have as github tags instead? It's BTW missing some version numbers, such as 2024.7.0:
https://github.com/uxlfoundation/scikit-learn-intelex/releases
| 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 |
There was a problem hiding this comment.
Question: what happens if something goes wrong during the build? For example, we might run into errors such as failing to import the modules from which autodoc generates documentation, which would manifest as a "warning" being issued but some docs still being built.
Could there be a check for build warnings that would make this script fail (avoiding pushing anything to GH) if something goes wrong?
| @@ -0,0 +1,19 @@ | |||
| [ | |||
There was a problem hiding this comment.
What about "stable" version tag in addition to latest?
|
Perhaps this PR could be a good opportunity to address one topic around the version numbers: in open source projects, version "latest" or "dev" is typically meant for docs from "latest commit of the master branch", while the "last released version" is typically "stable". This is the case for the docs of the scikit-learn package which this repository builds upon, and for most other machine-learning-related libraries such as gradient boosting frameworks and similar. Could we make the switch here so that the freshest release would be "stable" and have "latest" as something built periodically from the main branch? |
Description
replaces #1785
Version of docs built using CI: https://intelkevinputnam.github.io/scikit-learn-intelex/
There are two major changes in this PR:
Version Switching Support
All published versions must be tracked in doc/versions.json as this will allow all subsequent versions of the docs to automatically be able to switch to the latest without needing to rebuild the docs.
The version is supplied by the installed version of scikit-learn-intelex (latest by default in the CI script). This way building the docs is not dependent on the oneDAL environment with the goal of making it easier to contribute to and edit the docs. It should also make builds faster.
Since the move to the UXL Foundation, version switching is broken in the latest version of the docs because of there is a hard coded path to the versions.json that no longer exists (it was intel.github.com/scikit-learn-intelex). It also is now settable in the conf.py (html_context)
CI Deployment to GitHub Pages via GitHub Action
GitHub pages will be updated automatically. A new directory will be added for each version of scikit-learn-intelex. When the same version is built twice, it is overwritten. See
.github/workflows/publish.ymlfor the script. The branch will need to be changed tomainbefore it will work on the main branch. I'm not sure it is necessary to have the docs built on every merge intomain. Addingworkflow_dispatch:to the list of conditions for running the action can provide a handy "deploy whenever you feel like it" option.To build the docs locally, run
./build-docs.sh. Docs can be previewed locally by starting a web server (python3 -m http.server) in the_builddirectory and usinglocalhost:8000/scikit-learn-intelexas the URL.Checklist to comply with before moving PR from draft:
PR completeness and readability