refactor: use virtual environment to be consistent

_doc-build-linux/action.yml

@@ -185,56 +185,134 @@ runs:
         sudo apt-get update
         sudo apt-get install -y poppler-utils
 
-    - name: "Check if requirements.txt file exists"
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Determine context.
+
+    - name: "Determine GitHub environment variables"
       shell: bash
       run: |
-        echo "EXISTS_DOC_REQUIREMENTS=$(if [ -f ${{ inputs.requirements-file }} ]; then echo 'true'; else echo 'false'; fi)" >> $GITHUB_ENV
+        if [[ -f "pyproject.toml" ]] && grep -q 'build-backend = "poetry\.core\.masonry\.api"' "pyproject.toml"; then
+          echo "BUILD_BACKEND=$(echo 'poetry')" >> $GITHUB_ENV
+          echo "SPHINX_BUILD_MAKE=$(echo 'poetry run -- make')" >> $GITHUB_ENV
+        else
+          echo "BUILD_BACKEND=$(echo 'pip')" >> $GITHUB_ENV
+          echo "SPHINX_BUILD_MAKE=$(echo 'make')" >> $GITHUB_ENV
+        fi
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Build backend: ${{ env.BUILD_BACKEND }}
+          Sphinx build make: ${{ env.SPHINX_BUILD_MAKE }}
+
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Set up python to build the documentation.
+
+    # NOTE: Installation of poetry in a separate environment to the project to
+    # avoid situations in which both poetry and the project have shared
+    # dependencies with different version. This can lead to CICD failures. For
+    # more information, see https://github.com/ansys/actions/pull/560
+    - name: "Add pipx/bin directory to Github Path"
+      if: env.BUILD_BACKEND == 'poetry'
+      shell: bash
+      run: echo "${{ runner.temp }}/pipx/bin" >> $GITHUB_PATH
 
-    - name: "Print previous output"
+    # NOTE: Poetry uses virtual environments when installing a project. As we
+    # want to control that creation, we store POETRY_VIRTUALENVS_CREATE=false
+    # in the GitHub environment.
+    - name: "Set poetry environment variable(s)"
+      if: env.BUILD_BACKEND == 'poetry'
+      shell: bash
+      run: echo "POETRY_VIRTUALENVS_CREATE=false" >> $GITHUB_ENVs
+
+    # NOTE: Install pipx in a location that can be used in following CICD jobs
+    # but ensure that poetry is installed in a temporary folder cleaned before
+    # and after each job. This way poetry is kinda "installed at system level"
+    # making it available in the following call and installed in a different
+    # environment from the project.
+    - name: "Install poetry and create a virtual environment"
+      if: env.BUILD_BACKEND == 'poetry'
+      shell: bash
+      run: |
+        python -m pip install pipx
+        python -m pipx install poetry
+        python -m venv .venv
+      env:
+        PIPX_BIN_DIR: ${{ runner.temp }}/pipx/bin
+        PIPX_HOME : ${{ runner.temp }}/pipx/home
+
+    - name: "Create a virtual environment"
+      if: env.BUILD_BACKEND == 'pip'
       shell: bash
       run: |
-        echo "Output was found ${{ env.EXISTS_DOC_REQUIREMENTS }}"
+        python -m venv .venv
+
+    # ------------------------------------------------------------------------
 
     - name: "Update pip"
       shell: bash
-      run: python -m pip install -U pip
+      run: |
+        source .venv/bin/activate
+        python -m pip install -U pip
+
+    - name: "Check if requirements.txt file exists"
+      shell: bash
+      run: |
+        echo "EXISTS_DOC_REQUIREMENTS=$(if [ -f ${{ inputs.requirements-file }} ]; then echo 'true'; else echo 'false'; fi)" >> $GITHUB_ENV
 
     - name: "Install documentation dependencies from requirements file"
       shell: bash
       if: env.EXISTS_DOC_REQUIREMENTS == 'true'
       run: |
+        source .venv/bin/activate
         python -m pip install -r ${{ inputs.requirements-file }}
 
     - name: "Install Python library"
       shell: bash
       if: inputs.skip-install == 'false'
       run: |
-        python -m pip install .
+        source .venv/bin/activate
+        if [[ ${{ env.BUILD_BACKEND }} == 'poetry' ]]; then
+          poetry install
+        else
+          python -m pip install .
+        fi
 
     - name: "Install documentation dependencies from pyproject.toml"
       shell: bash
       if: env.EXISTS_DOC_REQUIREMENTS == 'false'
       run: |
-        if grep -q 'build-backend = "poetry\.core\.masonry\.api"' "pyproject.toml"; then
-          python -m pip install poetry
+        source .venv/bin/activate
+        if [[ ${{ env.BUILD_BACKEND }} == 'poetry' ]]; then
           poetry install --with doc
         else
           python -m pip install .[doc]
         fi
 
-    - name: "Determine make command context"
-      shell: bash
-      run: |
-        if [[ -f "pyproject.toml" ]] && grep -q 'build-backend = "poetry\.core\.masonry\.api"' "pyproject.toml"; then
-          echo "SPHINX_BUILD_MAKE=$(echo 'poetry run -- make')" >> $GITHUB_ENV
-        else
-          echo "SPHINX_BUILD_MAKE=$(echo 'make')" >> $GITHUB_ENV
-        fi
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Build HTML, PDF and JSON documentation.
 
     - name: "Build HTML, PDF, and JSON documentation"
       if: inputs.requires-xvfb == 'false'
       shell: bash
       run: |
+        source .venv/bin/activate
         ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
         ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
         if [[ ${{ inputs.check-links }} == 'true' ]];
@@ -250,6 +328,7 @@ runs:
       if: inputs.requires-xvfb == 'true'
       shell: bash
       run: |
+        source .venv/bin/activate
         xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
         xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
         if [[ ${{ inputs.check-links }} == 'true' ]];
@@ -274,6 +353,7 @@ runs:
       if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
       shell: bash
       run: |
+        source .venv/bin/activate
         python ${{ github.action_path }}/../doc-build/parse_doc_conf.py
 
     - uses: ansys/actions/_logging@main

_doc-build-windows/action.yml

@@ -33,8 +33,8 @@ description: |
   <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ is available
   after installing the documentation dependencies, the action uses it
   to generate documentation from the source. It requires that all the
-  documentation is contained in the ``doc/`` directory of a project. The
-  action locates the ``doc/make.bat`` and runs the ``make.bat html`` and
+  documentation is contained in the ``doc\`` directory of a project. The
+  action locates the ``doc\make.bat`` and runs the ``make.bat html`` and
   ``make.bat pdf`` commands. If desired, the ``make.bat json`` command can
   also be executed to generate JSON documentation.
 
@@ -100,7 +100,7 @@ inputs:
       Whether to add PDF and HTML documentation as assets of the HTML
       documentation. The HTML documentation is compressed before being added.
       The PDF file name is expected to be retrieved through the documentation's
-      configuration file 'conf.py' in 'doc/source'.
+      configuration file 'conf.py' in 'doc\source'.
 
       .. warning::
 
@@ -212,47 +212,116 @@ runs:
 
     # ------------------------------------------------------------------------
 
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Determine context.
+
+    - name: "Determine GitHub environment variables"
+      shell: powershell
+      run: |
+        if ((Test-Path "pyproject.toml") -and (Get-Content "pyproject.toml" | Select-String -Pattern 'build-backend = "poetry\.core\.masonry\.api"')) {
+          echo "BUILD_BACKEND=$(echo 'poetry')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          echo "SPHINX_BUILD_MAKE=$(echo 'poetry run -- make.bat')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+        } else {
+          echo "BUILD_BACKEND=$(echo 'pip')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          echo "SPHINX_BUILD_MAKE=$(echo '.\make.bat')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+        }
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Build backend: ${{ env.BUILD_BACKEND }}
+          Sphinx build make: ${{ env.SPHINX_BUILD_MAKE }}
+
+    # ------------------------------------------------------------------------
+
     - uses: ansys/actions/_logging@main
       with:
         level: "INFO"
         message: >
           Set up python to build the documentation.
 
-    - name: "Update pip"
+    # NOTE: Installation of poetry in a separate environment to the project to
+    # avoid situations in which both poetry and the project have shared
+    # dependencies with different version. This can lead to CICD failures. For
+    # more information, see https://github.com/ansys/actions/pull/560
+    - name: "Add pipx/bin directory to Github Path"
+      if: env.BUILD_BACKEND == 'poetry'
       shell: powershell
-      run: python -m pip install -U pip
+      run: echo "${{ runner.temp }}/pipx/bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
 
-    - name: Check if requirements.txt file exists
+    # NOTE: Poetry uses virtual environments when installing a project. As we
+    # want to control that creation, we store POETRY_VIRTUALENVS_CREATE=false
+    # in the GitHub environment.
+    - name: "Set poetry environment variable(s)"
+      if: env.BUILD_BACKEND == 'poetry'
+      shell: powershell
+      run: echo "POETRY_VIRTUALENVS_CREATE=$(echo false)" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+    # NOTE: Install pipx in a location that can be used in following CICD jobs
+    # but ensure that poetry is installed in a temporary folder cleaned before
+    # and after each job. This way poetry is kinda "installed at system level"
+    # making it available in the following call and installed in a different
+    # environment from the project.
+    - name: "Install poetry and create a virtual environment"
+      if: env.BUILD_BACKEND == 'poetry'
       shell: powershell
       run: |
-        echo "EXISTS_DOC_REQUIREMENTS=$(if (Test-Path '${{ inputs.requirements-file }}') { echo 'true' } else { echo 'false' })" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
+        python -m pip install pipx
+        python -m pipx install poetry
+        python -m venv .venv
+      env:
+        PIPX_BIN_DIR: ${{ runner.temp }}/pipx/bin
+        PIPX_HOME : ${{ runner.temp }}/pipx/home
+
+    - name: "Create a virtual environment"
+      if: env.BUILD_BACKEND == 'pip'
+      shell: powershell
+      run: python -m venv .venv
+
+    # ------------------------------------------------------------------------
+
+    - name: "Update pip"
+      shell: powershell
+      run: |
+        .venv\Scripts\Activate.ps1
+        python -m pip install -U pip
 
-    - name: Print previous output
+    - name: "Check if requirements.txt file exists"
       shell: powershell
       run: |
-        echo "Output was found ${{ env.EXISTS_DOC_REQUIREMENTS }}"
+        echo "EXISTS_DOC_REQUIREMENTS=$(if (Test-Path '${{ inputs.requirements-file }}') { echo 'true' } else { echo 'false' })" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
 
     - name: Install documentation dependencies from requirements file
       shell: powershell
       if: ${{ env.EXISTS_DOC_REQUIREMENTS == 'true' }}
       run: |
+        .venv\Scripts\Activate.ps1
         python -m pip install -r ${{ inputs.requirements-file }}
 
     - name: Install Python library
       shell: powershell
       if: ${{ inputs.skip-install == 'false' }}
       run: |
-        python -m pip install .
+        .venv\Scripts\Activate.ps1
+        if ("${{ env.BUILD_BACKEND }}" -eq 'poetry' ) {
+          poetry install
+        } else {
+          python -m pip install .
+        }
 
     - name: Install documentation dependencies from pyproject.toml
       shell: powershell
       if: ${{ env.EXISTS_DOC_REQUIREMENTS == 'false' }}
       run: |
-        if (Get-Content "pyproject.toml" | Select-String -Pattern 'build-backend = "poetry\.core\.masonry\.api"') {
-            python -m pip install poetry
-            poetry install --with doc
+        .venv\Scripts\Activate.ps1
+        if ("${{ env.BUILD_BACKEND }}" -eq 'poetry' ) {
+          poetry install --with doc
         } else {
-            python -m pip install .[doc]
+          python -m pip install .[doc]
         }
 
     # ------------------------------------------------------------------------
@@ -263,19 +332,11 @@ runs:
         message: >
           Build HTML, PDF and JSON documentation.
 
-    - name: Determine command context
-      shell: powershell
-      run: |
-        if ((Test-Path "pyproject.toml") -and (Get-Content "pyproject.toml" | Select-String -Pattern 'build-backend = "poetry\.core\.masonry\.api"')) {
-          echo "SPHINX_BUILD_MAKE=$(echo 'poetry run -- doc\make.bat')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
-        } else {
-          echo "SPHINX_BUILD_MAKE=$(echo 'doc\make.bat')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
-        }
-
     - name: Build HTML, PDF, and JSON documentation
       shell: powershell
       run: |
-        echo "Sphinx build make value is ${{ env.SPHINX_BUILD_MAKE }}"
+        .venv\Scripts\Activate.ps1
+        cd doc
         ${{ env.SPHINX_BUILD_MAKE }} html SPHINXOPTS="${{ inputs.sphinxopts }}"
         ${{ env.SPHINX_BUILD_MAKE }} pdf
         if ("${{ inputs.check-links }}" -eq 'true' ) {
@@ -298,6 +359,7 @@ runs:
       if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
       shell: powershell
       run: |
+        .venv\Scripts\Activate.ps1
         python ${{ github.action_path }}\..\doc-build\parse_doc_conf.py
 
     - uses: ansys/actions/_logging@main