Backfill documentation #22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Backfill documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| tag: | |
| description: 'Tag to backfill from' | |
| required: true | |
| type: string | |
| python-version: | |
| description: 'Python version to build with (default: the one recorded in the tag)' | |
| required: false | |
| type: string | |
| compiler-version: | |
| description: 'DPC++ version to build with (default: the one required by the tag)' | |
| required: false | |
| type: string | |
| permissions: | |
| contents: read | |
| env: | |
| CHECK_CONFIG_SCRIPT: "import sys; from packaging.version import parse; print('true' if parse('0.17.0') <= parse(sys.argv[1]) < parse('0.22.0') else 'false')" | |
| # dpctl gained NumPy 2 support in 0.18.0dev1; earlier tags fail to build against it. | |
| NUMPY_SPEC_SCRIPT: "import sys; from packaging.version import parse; print('numpy<2' if parse(sys.argv[1]) < parse('0.18.0dev1') else 'numpy')" | |
| # Used only for tags that predate the docs workflow and so record no version. | |
| DEFAULT_PYTHON_VERSION: '3.10' | |
| jobs: | |
| build-and-backfill: | |
| name: Build and Backfill Documentation | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 240 | |
| permissions: | |
| contents: write | |
| actions: write | |
| steps: | |
| - name: Cancel Previous Runs | |
| uses: styfle/cancel-workflow-action@d07a454dad7609a92316b57b23c9ccfd4f59af66 # 0.13.1 | |
| with: | |
| access_token: ${{ github.token }} | |
| - name: Add Intel repository | |
| run: | | |
| wget -qO- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \ | |
| | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null | |
| echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main" \ | |
| | sudo tee /etc/apt/sources.list.d/oneAPI.list | |
| sudo apt update | |
| - name: Checkout repo at tag | |
| uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| ref: ${{ github.event.inputs.tag }} | |
| fetch-depth: 0 | |
| persist-credentials: false | |
| - name: Resolve DPC++ version for the tag | |
| id: resolve-compiler | |
| env: | |
| TAG: ${{ github.event.inputs.tag }} | |
| COMPILER_VERSION_INPUT: ${{ github.event.inputs.compiler-version }} | |
| run: | | |
| COMPILER_PACKAGE=intel-oneapi-compiler-dpcpp-cpp | |
| if [[ -n "${COMPILER_VERSION_INPUT}" ]]; then | |
| COMPILER_VERSION="${COMPILER_VERSION_INPUT}" | |
| echo "Using DPC++ ${COMPILER_VERSION} requested via workflow input." | |
| else | |
| # build against compiler version declared in the conda recipe | |
| COMPILER_VERSION=$(grep -oP 'required_compiler_version\s*=\s*"\K[^"]+' \ | |
| conda-recipe/meta.yaml 2>/dev/null | head -n 1 || true) | |
| if [[ -z "${COMPILER_VERSION}" ]]; then | |
| echo "${TAG} declares no required_compiler_version. Using the latest DPC++." | |
| echo "package=${COMPILER_PACKAGE}" >> "$GITHUB_OUTPUT" | |
| exit 0 | |
| fi | |
| echo "${TAG} requires DPC++ ${COMPILER_VERSION}." | |
| fi | |
| VERSIONED_PACKAGE="${COMPILER_PACKAGE}-$(cut -d. -f1,2 <<< "${COMPILER_VERSION}")" | |
| if apt-cache show "${VERSIONED_PACKAGE}" > /dev/null 2>&1; then | |
| COMPILER_PACKAGE="${VERSIONED_PACKAGE}" | |
| echo "Installing ${COMPILER_PACKAGE}." | |
| else | |
| echo "::warning::${VERSIONED_PACKAGE} is not in the Intel apt repository. Using the latest DPC++ instead." | |
| fi | |
| echo "package=${COMPILER_PACKAGE}" >> "$GITHUB_OUTPUT" | |
| - name: Install Intel OneAPI | |
| env: | |
| COMPILER_PACKAGE: ${{ steps.resolve-compiler.outputs.package }} | |
| run: | | |
| sudo apt install "${COMPILER_PACKAGE}" | |
| sudo apt install intel-oneapi-tbb | |
| sudo apt install intel-oneapi-umf | |
| sudo apt install hwloc | |
| - name: Install Lua | |
| run: | | |
| sudo apt-get install liblua5.2-dev | |
| - name: Install Doxygen | |
| run: | | |
| sudo apt-get install doxygen | |
| - name: Install Ninja | |
| run: | | |
| sudo apt-get install ninja-build | |
| - name: Resolve Python version for the tag | |
| id: resolve-python | |
| env: | |
| TAG: ${{ github.event.inputs.tag }} | |
| PYTHON_VERSION_INPUT: ${{ github.event.inputs.python-version }} | |
| run: | | |
| if [[ -n "${PYTHON_VERSION_INPUT}" ]]; then | |
| PYTHON_VERSION="${PYTHON_VERSION_INPUT}" | |
| echo "Using Python ${PYTHON_VERSION} requested via workflow input." | |
| else | |
| # reuse pin from generate-docs.yml at the tag | |
| PYTHON_VERSION=$(grep -oP "python-version:\s*'?\K[0-9]+\.[0-9]+" \ | |
| .github/workflows/generate-docs.yml 2>/dev/null | head -n 1 || true) | |
| if [[ -z "${PYTHON_VERSION}" ]]; then | |
| PYTHON_VERSION="${DEFAULT_PYTHON_VERSION}" | |
| echo "${TAG} records no docs Python version; falling back to ${PYTHON_VERSION}." | |
| else | |
| echo "Using Python ${PYTHON_VERSION} as recorded at ${TAG}." | |
| fi | |
| fi | |
| echo "python-version=${PYTHON_VERSION}" >> "$GITHUB_OUTPUT" | |
| - name: Setup Python | |
| uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 | |
| with: | |
| python-version: ${{ steps.resolve-python.outputs.python-version }} | |
| architecture: x64 | |
| - name: Install sphinx dependencies | |
| shell: bash -l {0} | |
| env: | |
| TAG: ${{ github.event.inputs.tag }} | |
| run: | | |
| pip install packaging | |
| NUMPY_SPEC=$(python -c "$NUMPY_SPEC_SCRIPT" "$TAG") | |
| echo "Building against ${NUMPY_SPEC}." | |
| pip install "${NUMPY_SPEC}" cython setuptools">=70.1" scikit-build cmake sphinx"<7.2" pydot graphviz furo \ | |
| sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx-design \ | |
| sphinxcontrib-jsmath sphinx-copybutton sphinxcontrib-spelling \ | |
| versioneer[toml]==0.29 | |
| - name: Inject new docs configuration | |
| shell: bash -l {0} | |
| env: | |
| TAG: ${{ github.event.inputs.tag }} | |
| run: | | |
| git fetch origin master | |
| # a tag cannot list the versions released after it, so the version list | |
| # behind the sidebar dropdown always has to come from master | |
| git checkout origin/master -- docs/doc_versions.txt | |
| NEEDS_CONFIG=$(python -c "$CHECK_CONFIG_SCRIPT" "$TAG") | |
| if [[ "${NEEDS_CONFIG}" == "true" ]]; then | |
| git checkout origin/master -- docs/doc_sources/conf.py.in \ | |
| docs/doc_sources/_templates/versions.html | |
| else | |
| echo "Tag already has the current docs template, only the version list was injected." | |
| fi | |
| - name: Build dpctl+docs | |
| shell: bash -l {0} | |
| run: | | |
| # Ensure that SYCL libraries are on LD_LIBRARY_PATH | |
| 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 setup.py build_ext --inplace --generator=Ninja --build-type=Release \ | |
| -- \ | |
| -DCMAKE_C_COMPILER:PATH="$(which icx)" \ | |
| -DCMAKE_CXX_COMPILER:PATH="$(which icpx)" \ | |
| -DDPCTL_GENERATE_DOCS=ON \ | |
| -DDPCTL_ENABLE_DOXYREST=ON \ | |
| -DDPCTL_USE_MULTIVERSION_TEMPLATE=ON \ | |
| -DDoxyrest_DIR="$(pwd)/doxyrest-2.1.2-linux-amd64" \ | |
| -DCMAKE_VERBOSE_MAKEFILE=ON | |
| python -m pip install -e . --no-build-isolation --no-deps | |
| 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 | |
| git clean -dfx | |
| popd | |
| git reset --hard | |
| - name: Publish docs | |
| env: | |
| TAG: ${{ github.event.inputs.tag }} | |
| shell: bash -l {0} | |
| run: | | |
| git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/dpctl.git | |
| git fetch tokened_docs | |
| git checkout --track tokened_docs/gh-pages | |
| # replace the directory outright so a re-run cannot merge into stale docs | |
| rm -rf "${TAG:?}" | |
| mv ~/docs "${TAG}" || exit 1 | |
| git add --all "${TAG}" | |
| git config user.name 'github-actions[doc-deploy-bot]' | |
| git config user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com' | |
| git commit -m "Docs backfilled for ${TAG}." | |
| git push tokened_docs gh-pages |