feat: add upload assets to doc-build

_doc-build-linux/action.yml

@@ -123,6 +123,23 @@ inputs:
     required: true
     type: boolean
 
+  add-pdf-html-docs-as-assets:
+    description: |
+      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'.
+
+      .. warning::
+
+          The HTML files are expected to be contained in ``doc/_build`` and the
+          PDF file is copied in ``doc/_build/html/_static/assets/download``.
+          If such directories do not exist in your repo, the action will fail.
+
+    required: true
+    type: boolean
+
+
 runs:
   using: "composite"
   steps:
@@ -234,6 +251,117 @@ runs:
           xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc json SPHINXOPTS="${{ inputs.sphinxopts }}"
         fi
 
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      with:
+        level: "INFO"
+        message: >
+          Set environment variable PDF_FILENAME.
+
+    - name: Parse PDF file name
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: bash
+      run: |
+        python ${{ github.action_path }}/../doc-build/parse_doc_conf.py
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true' ) && (env.PDF_FILENAME == '') }}
+      with:
+        level: "ERROR"
+        message: >
+          Unable to determine PDF filename using conf.py file.
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true' ) && (env.PDF_FILENAME != '') }}
+      with:
+        level: "INFO"
+        message: >
+          Environment variable PDF_FILENAME setted to ${{ env.PDF_FILENAME }}.
+
+    # ------------------------------------------------------------------------
+    - uses: ansys/actions/_logging@main
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      with:
+        level: "INFO"
+        message: >
+          Check if expected directories exist.
+
+    - name: Set expected build directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: bash
+      run: |
+        echo "EXPECTED_BUILD_DIR='doc/_build'" >> $GITHUB_ENV
+
+    - name: Check expected build directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: bash
+      run: |
+        echo "EXISTS_EXPECTED_BUILD_DIR=$( [ -d ${{ env.EXPECTED_BUILD_DIR }} ] && echo 'true' || echo 'false' )" >> $GITHUB_ENV
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_BUILD_DIR == 'false') }}
+      with:
+        level: "ERROR"
+        message: >
+          Expected build directory ${{ env.EXPECTED_BUILD_DIR }} does not exist.
+
+    - name: Set expected download directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: bash
+      run: |
+        echo "EXPECTED_DOWNLOAD_DIR=$(echo '${{ env.EXPECTED_BUILD_DIR }}/html/_static/assets/download')" >> $GITHUB_ENV
+
+    - name: Check expected download directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: bash
+      run: |
+        echo "EXISTS_EXPECTED_DOWNLOAD_DIR=$( [ -d '${{ env.EXPECTED_DOWNLOAD_DIR }}' ] && echo 'true' || echo 'false' )" >> $GITHUB_ENV
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_DOWNLOAD_DIR == 'false') }}
+      with:
+        level: "WARNING"
+        message: >
+          Expected build directory ${{ env.EXPECTED_DOWNLOAD_DIR }} does not exist.  Creating it...
+
+    - name: Create expected download directory
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_DOWNLOAD_DIR == 'false') }}
+      shell: bash
+      run: |
+        mkdir -p ${{ env.EXPECTED_DOWNLOAD_DIR }}
+
+    # ------------------------------------------------------------------------
+
+    - name: Check build directory
+      uses: ansys/actions/_logging@main
+      if: inputs.add-pdf-html-docs-as-assets == 'true'
+      with:
+        level: "INFO"
+        message: >
+          Add PDF and HTML documentation as assets.
+
+    - name: Compress HTML documentation
+      uses: vimtor/[email protected]
+      with:
+        files: ${{ env.EXPECTED_BUILD_DIR }}/html
+        dest: documentation-html.zip
+
+    - name: Add assets to HTML docs
+      shell: bash
+      run: |
+        mv documentation-html.zip ${{ env.EXPECTED_DOWNLOAD_DIR }}
+        if [ -e  "${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }}" ]; then
+            cp ${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }} ${{ env.EXPECTED_DOWNLOAD_DIR }}
+            echo "File ${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }} has been copied."
+        else
+            cp ${{ env.EXPECTED_BUILD_DIR }}/latex/*.pdf ${{ env.EXPECTED_DOWNLOAD_DIR }}
+            echo "Couldn't find ${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }}, every existing PDF file has been copied."
+        fi
+
+    # ------------------------------------------------------------------------
+
     - name: "Upload HTML documentation artifact"
       uses: actions/upload-artifact@v4
       with:

_doc-build-windows/action.yml

@@ -115,6 +115,23 @@ inputs:
     required: true
     type: boolean
 
+  add-pdf-html-docs-as-assets:
+    description: |
+      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'.
+
+      .. warning::
+
+          The HTML files are expected to be contained in ``doc\_build`` and the
+          PDF file is copied in ``doc\_build\html\_static\assets\download``.
+          If such directories do not exist in your repo, the action will fail.
+
+    required: true
+    type: boolean
+
+
 runs:
   using: "composite"
   steps:
@@ -258,6 +275,111 @@ runs:
 
     # ------------------------------------------------------------------------
 
+    - uses: ansys/actions/_logging@main
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      with:
+        level: "INFO"
+        message: >
+          Set environment variable PDF_FILENAME.
+
+    - name: Parse PDF file name
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: powershell
+      run: |
+        python ${{ github.action_path }}\..\doc-build\parse_doc_conf.py
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true' ) && (env.PDF_FILENAME == '') }}
+      with:
+        level: "ERROR"
+        message: >
+          Unable to determine PDF filename using conf.py file.
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true' ) && (env.PDF_FILENAME != '') }}
+      with:
+        level: "INFO"
+        message: >
+          Environment variable PDF_FILENAME setted to ${{ env.PDF_FILENAME }}.
+
+    # ------------------------------------------------------------------------
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      with:
+        level: "INFO"
+        message: >
+          Check if expected directories exist.
+
+    - name: Set expected build directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: powershell
+      run: |
+        echo "EXPECTED_BUILD_DIR=$(echo 'doc\_build')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+    - name: Check expected build directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: powershell
+      run: |
+        echo "EXISTS_EXPECTED_BUILD_DIR=$(if (Test-Path '${{ env.EXPECTED_BUILD_DIR }}') { echo 'true' } else { echo 'false' })" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_BUILD_DIR == 'false') }}
+      with:
+        level: "ERROR"
+        message: >
+          Expected build directory ${{ env.EXPECTED_BUILD_DIR }} does not exist.
+
+    - name: Set expected download directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: powershell
+      run: |
+        echo "EXPECTED_DOWNLOAD_DIR=$(echo '${{ env.EXPECTED_BUILD_DIR }}\html\_static\assets\download')" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+    - name: Check expected download directory
+      if: ${{ inputs.add-pdf-html-docs-as-assets == 'true' }}
+      shell: powershell
+      run: |
+        echo "EXISTS_EXPECTED_DOWNLOAD_DIR=$(if (Test-Path '${{ env.EXPECTED_DOWNLOAD_DIR }}') { echo 'true' } else { echo 'false' })" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
+
+    - uses: ansys/actions/_logging@main
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_DOWNLOAD_DIR == 'false') }}
+      with:
+        level: "WARNING"
+        message: >
+          Expected build directory ${{ env.EXPECTED_DOWNLOAD_DIR }} does not exist. Creating it...
+
+    - name: Create expected download directory
+      if: ${{ (inputs.add-pdf-html-docs-as-assets == 'true') && (env.EXISTS_EXPECTED_DOWNLOAD_DIR == 'false') }}
+      shell: powershell
+      run: |
+        New-Item -ItemType directory ${{ env.EXPECTED_DOWNLOAD_DIR }}
+
+    # ------------------------------------------------------------------------
+
+    - name: Check build directory
+      uses: ansys/actions/_logging@main
+      if: inputs.add-pdf-html-docs-as-assets == 'true'
+      with:
+        level: "INFO"
+        message: >
+          Add PDF and HTML documentation as assets.
+
+    - name: Add assets to HTML docs
+      shell: powershell
+      run: |
+        zip -r documentation-html.zip ${{ env.EXPECTED_BUILD_DIR }}\html
+        mv documentation-html.zip ${{ env.EXPECTED_DOWNLOAD_DIR }}
+        if (Test-Path $${{ env.EXPECTED_BUILD_DIR }}\latex\${{ env.PDF_FILENAME }}) {
+          cp ${{ env.EXPECTED_BUILD_DIR }}\latex\${{ env.PDF_FILENAME }} ${{ env.EXPECTED_DOWNLOAD_DIR }}
+          Write-Output "File ${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }} has been copied."
+        } else {
+          cp ${{ env.EXPECTED_BUILD_DIR }}/latex/*.pdf ${{ env.EXPECTED_DOWNLOAD_DIR }}
+          Write-Output "Couldn't find ${{ env.EXPECTED_BUILD_DIR }}/latex/${{ env.PDF_FILENAME }}, every existing PDF file has been copied."
+        }
+
+    # ------------------------------------------------------------------------
+
     - uses: ansys/actions/_logging@main
       with:
         level: "INFO"

doc-build/action.yml

@@ -150,6 +150,24 @@ inputs:
     required: false
     type: boolean
 
+  add-pdf-html-docs-as-assets:
+    description: |
+      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 the same as the project name defined
+      in the pyproject.toml file. Default value is ``false``.
+
+      .. warning::
+
+          The HTML files are expected to be contained in ``doc/_build`` and the
+          PDF file is copied in ``doc/_build/html/_static/assets/download``.
+          If such directories do not exist in your repo, the action will fail.
+
+    default: false
+    required: false
+    type: boolean
+
+
 runs:
   using: "composite"
   steps:
@@ -170,7 +188,7 @@ runs:
 
     - name: Documentation build (Linux)
       if: ${{ runner.os == 'Linux' }}
-      uses: ansys/actions/_doc-build-linux@main
+      uses: ansys/actions/_doc-build-linux@feat/doc-build-upload-assets
       with:
         python-version: ${{ inputs.python-version }}
         use-python-cache: ${{ inputs.use-python-cache }}
@@ -183,6 +201,7 @@ runs:
         checkout: ${{ inputs.checkout }}
         skip-json-build: ${{ inputs.skip-json-build }}
         check-links: ${{ inputs.check-links }}
+        add-pdf-html-docs-as-assets: ${{ inputs.add-pdf-html-docs-as-assets }}
 
     # ------------------------------------------------------------------------
 
@@ -196,7 +215,7 @@ runs:
 
     - name: Documentation build (Windows)
       if: ${{ runner.os == 'Windows' }}
-      uses: ansys/actions/_doc-build-windows@main
+      uses: ansys/actions/_doc-build-windows@feat/doc-build-upload-assets
       with:
         python-version: ${{ inputs.python-version }}
         use-python-cache: ${{ inputs.use-python-cache }}
@@ -208,3 +227,4 @@ runs:
         checkout: ${{ inputs.checkout }}
         skip-json-build: ${{ inputs.skip-json-build }}
         check-links: ${{ inputs.check-links }}
+        add-pdf-html-docs-as-assets: ${{ inputs.add-pdf-html-docs-as-assets }}