generate-documentation.yml

# Copyright 2024 CS Group
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

name: Generate documentation

# TODO: when to generate the doc ?
# For now, only for new git tags (including hierarchical tags like v1.0/beta), or manually
on:
    push:      
    workflow_dispatch:

env:
  PYTHON_VERSION: 3.11

jobs:
  generate-documentation:
    name: Generate documentation
    runs-on: ubuntu-latest
    permissions:
      packages: read # to pull docker images when running build_aggregated_openapi.sh
      contents: write # to publish the generated documentation
    steps:      
      - uses: actions/checkout@v4         
      - uses: ./.github/actions/install-python

      - name: Clone RS-Server/RS-Client/RS-Demo/RS-Infra/RS-Helm
        run: |
          set -x           
          pwd     
          ls -all          
          cd docs

          # We want to use the same branch name (if it exists) in the other 
          # cloned repositories as the current branch name
          branch_name=${{ github.ref_name }}

          #
          # Clone public rspy repositories

          git clone https://github.com/RS-PYTHON/rs-server.git
          (cd rs-server; git checkout $branch_name || git checkout develop)

          git clone https://github.com/RS-PYTHON/rs-client-libraries.git
          (cd rs-client-libraries; git checkout $branch_name || git checkout develop)
          
          git clone https://github.com/RS-PYTHON/rs-demo.git
          (cd rs-demo; git checkout $branch_name || git checkout develop)

          ls -all

          # Clone private rspy repositories.
          # Use the ssh private key from: https://github.com/RS-PYTHON/rs-documentation/settings/secrets/actions
          # And the public keys from: 
            #   https://github.com/RS-PYTHON/rs-infra-core/settings/keys
            #   https://github.com/RS-PYTHON/rs-helm/settings/keys

          eval "$(ssh-agent -s)"
          ssh-add - <<< "${{ secrets.RS_INFRA_PRIVATE_SSH_KEY }}"
          git clone --depth 1 git@github.com:RS-PYTHON/rs-infra-core.git
          cd rs-infra-core
          git checkout $branch_name || git checkout develop
          git sparse-checkout init --no-cone
          echo "/docs/" > .git/info/sparse-checkout
          echo "/LICENSE" >> .git/info/sparse-checkout
          echo "/NOTICE.md" >> .git/info/sparse-checkout
          echo "/README.md" >> .git/info/sparse-checkout
          git read-tree -mu HEAD
          ls -all
          cd ..
          
          eval "$(ssh-agent -s)"
          ssh-add - <<< "${{ secrets.RS_HELM_PRIVATE_SSH_KEY }}"
          git clone git@github.com:RS-PYTHON/rs-helm.git
          (cd rs-helm; git checkout $branch_name || git checkout develop)
        working-directory: .
        shell: bash

      - name: Install dependencies
        uses: ./.github/actions/poetry-install

      - name: Generate Markdown HTML documentation
        run: |
          set -x           
          pwd          
          ls -all          
          sleep 2
          poetry run mkdocs gh-deploy --force
        working-directory: .
        shell: bash