refactor: use virtual environment to be consistent

_doc-build-linux/action.yml

@@ -179,80 +179,142 @@ 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 }}
 
-    - name: "Print previous output"
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Set up python to build the documentation.
+
+    - name: "Set poetry environment variable(s) (if required)"
       shell: bash
+      if: env.BUILD_BACKEND == 'poetry'
       run: |
-        echo "Output was found ${{ env.EXISTS_DOC_REQUIREMENTS }}"
+        # For projects using poetry, do not use a virtual environment.
+        # Poetry uses virtual environments to install its dependencies, but this might
+        # lead to problems if it is not activated prior to executing poetry commands.
+        # Store POETRY_VIRTUALENVS_CREATE=false in the GitHub environment to prevent
+        # poetry from creating a virtual environment.
+        #
+        echo "POETRY_VIRTUALENVS_CREATE=false" >> $GITHUB_ENV
 
     - 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 poetry (if required)"
+      shell: bash
+      if: env.BUILD_BACKEND == 'poetry'
+      run: |
+        source .venv/bin/activate
+        python -m pip install poetry
+
     - 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"
+    - name: "Move into doc foled"
       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
+        cd doc
+
+    # ------------------------------------------------------------------------
+
+    - 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: |
-        ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
-        ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
+        source .venv/bin/activate
+        ${{ env.SPHINX_BUILD_MAKE }} html SPHINXOPTS="${{ inputs.sphinxopts }}"
+        ${{ env.SPHINX_BUILD_MAKE }} pdf
         if [[ ${{ inputs.check-links }} == 'true' ]];
         then
-          ${{ env.SPHINX_BUILD_MAKE }} -C doc linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
+          ${{ env.SPHINX_BUILD_MAKE }} linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
         fi
         if [[ ${{ inputs.skip-json-build }} == 'false' ]];
         then
-          ${{ env.SPHINX_BUILD_MAKE }} -C doc json SPHINXOPTS="${{ inputs.sphinxopts }}"
+          ${{ env.SPHINX_BUILD_MAKE }} json SPHINXOPTS="${{ inputs.sphinxopts }}"
         fi
 
     - name: "Build HTML, PDF, and JSON documentation using xvfb"
       if: inputs.requires-xvfb == 'true'
       shell: bash
       run: |
-        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
-        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
+        source .venv/bin/activate
+        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} html SPHINXOPTS="${{ inputs.sphinxopts }}"
+        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} pdf
         if [[ ${{ inputs.check-links }} == 'true' ]];
         then
-          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
+          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
         fi
         if [[ ${{ inputs.skip-json-build }} == 'false' ]];
         then
-          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc json SPHINXOPTS="${{ inputs.sphinxopts }}"
+          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} json SPHINXOPTS="${{ inputs.sphinxopts }}"
         fi
 
     # ------------------------------------------------------------------------
@@ -268,6 +330,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
@@ -297,7 +360,7 @@ runs:
       if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
       shell: bash
       run: |
-        echo "EXPECTED_BUILD_DIR=doc/_build" >> $GITHUB_ENV
+        echo "EXPECTED_BUILD_DIR=_build" >> $GITHUB_ENV
 
     - name: Check expected build directory
       if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
@@ -373,20 +436,20 @@ runs:
       uses: actions/upload-artifact@v4
       with:
         name: documentation-html
-        path: doc/_build/html
+        path: _build/html
         retention-days: 7
 
     - name: "Upload PDF documentation artifact"
       uses: actions/upload-artifact@v4
       with:
         name: documentation-pdf
-        path: doc/_build/latex/*.pdf
+        path: _build/latex/*.pdf
         retention-days: 7
 
     - name: "Upload JSON documentation artifact"
       uses: actions/upload-artifact@v4
       if: inputs.skip-json-build == 'false'
       with:
         name: documentation-json
-        path: doc/_build/json
+        path: _build/json
         retention-days: 7