Fix/redo API docs generation (#454)

Fixes and reworks how we generate the docs. Instead of docker files that build the documentation, it uses the containers provided by Github actions

---------

Signed-off-by: Addisu Z. Taddese <[email protected]>

Author: azeey

.github/workflows/labeler.yml

@@ -4,6 +4,7 @@ on:
 
 jobs:
   labeler:
+    if: github.repository_owner == 'gazebosim'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/labeler@v2

.github/workflows/nightly-upload.yml

@@ -1,4 +1,4 @@
-name: Upload docs to production
+name: Deploy API Docs
 
 on:
   schedule:
@@ -7,32 +7,82 @@ on:
   workflow_dispatch:
 
 jobs:
+  build:
+    name: 'Build API Docs (${{ matrix.gazebo_distribution }})'
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:${{ matrix.ubuntu_distribution }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - ubuntu_distribution: focal
+            gazebo_distribution: citadel
+
+          - ubuntu_distribution: focal
+            gazebo_distribution: fortress
+
+          - ubuntu_distribution: focal
+            gazebo_distribution: garden
+
+          - ubuntu_distribution: jammy
+            gazebo_distribution: harmonic
+    steps:
+      - uses: ros-tooling/[email protected]
+      - name: 'Set up Gazebo'
+        uses: gazebo-tooling/setup-gazebo@1f55cec330de851fa373f1ade8ac6b7ddfe6f013
+        with:
+          required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
+      - name: 'Add Doxygen'
+        run: sudo apt-get install -y doxygen graphviz
+      - name: 'Add missing dependencies'
+        run: sudo apt-get install -y libopengl-dev
+      - name: 'Build Docs'
+        run: |
+          mkdir -p ws/src
+          cd ws/src
+          vcs import --input https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-${{ matrix.gazebo_distribution}}.yaml
+          rm -rf sdformat
+          rm -rf gz-tools
+          sudo DEBIAN_FRONTEND=noninteractive apt-get -y install $(sort -u $(find . -iname 'packages-'${{ matrix.ubuntu_distribution}}'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | tr '\n' ' ')
+          cd ..
+          colcon build --merge-install --event-handlers console_cohesion+ --cmake-args -DBUILD_DOCS=ON -DBUILD_TESTING=OFF --cmake-target doc
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: api-docs-${{ matrix.gazebo_distribution }}
+          path: ws/build/**/doxygen/html
+
   upload:
     name: Upload docs to production
-    runs-on: ubuntu-20.04
+    needs: build
+    runs-on: ubuntu-latest
     permissions:
       id-token: write
       contents: read
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
     - name: Configure AWS Credentials
       id: creds
       uses: aws-actions/configure-aws-credentials@v4
       with:
         aws-region: us-east-1
         role-to-assume: arn:aws:iam::200670743174:role/github-oidc-deployment-gz-web-app
-        # Need to run ./build_docs.sh
-        output-credentials: true
+    - uses: actions/download-artifact@v4
+      id: download
+      with:
+        path: .api-docs
+        pattern: api-docs-*
+        merge-multiple: true
+    - name: 'Restructure API Docs'
+      run: python3 tools/restructure_doxygen_artifacts.py ${{steps.download.outputs.download-path}} .api-out
+    - uses: actions/upload-artifact@v4
+      with:
+        name: api-docs
+        path: .api-out/*
     - name: Run nightly upload
-      run: |
-        cd tools && ./build_docs.sh all
-      shell: bash
-      env:
-        GZ_VERSION_PASSWORD: ${{ secrets.GZ_VERSION_PASSWORD }}
-        AWS_ACCESS_KEY_ID: ${{ steps.creds.outputs.aws-access-key-id }}
-        AWS_SECRET_ACCESS_KEY: ${{ steps.creds.outputs.aws-secret-access-key }}
-        AWS_SESSION_TOKEN: ${{ steps.creds.outputs.aws-session-token }}
+      run: aws s3 sync .api-out/ s3://gazebosim.org/api/
     - name: Invalidate Cloudfront distribution
       run: |
         aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} --paths '/*' --region us-east-1

.github/workflows/triage.yml

@@ -6,6 +6,7 @@ on:
 name: Ticket opened
 jobs:
   assign:
+    if: github.repository_owner == 'gazebosim'
     name: Add ticket to inbox
     runs-on: ubuntu-latest
     steps:

tools/restructure_doxygen_artifacts.py

@@ -0,0 +1,56 @@
+# Usage
+#   /restructure_doxygen_artifacts.py <path_to_artifacts> <output_directory>
+#
+# Given a directory containing merged doxygen build artifacts, this script reorganizes them so they
+# can be deployed to the website
+# This assumes the following directory structure:
+#   ignition-utils1
+#     doxygen
+#       html
+#   gz-utils2
+#     doxygen
+#       html
+#   ignition-math6
+#     doxygen
+#       html
+#   gz-math7
+#     doxygen
+#       html
+#   ...
+#
+#   The result should look like
+#   utils
+#     1 (content of ignition-utils1/doxygen/html)
+#     2 (content of gz-utils2/doxygen/html)
+#   math
+#     6 (content of ignition-math6/doxygen/html)
+#     7 (content of gz-math7/doxygen/html)
+
+import re
+import sys
+import pathlib
+import shutil
+
+input_dir = pathlib.Path(sys.argv[1])
+output_dir = pathlib.Path(sys.argv[2])
+output_dir.mkdir(exist_ok=True)
+
+re_expr = R"(ignition|gz)-([a-z_]*)(\d*)"
+
+
+def copy_library(lib_html, lib_name, lib_version):
+    output_lib_dir = output_dir / lib_name / lib_version
+    output_lib_dir.mkdir(exist_ok=True, parents=True)
+    print(f"{lib_html} -> {output_lib_dir}")
+    shutil.copytree(lib_html, output_lib_dir, dirs_exist_ok=True)
+
+
+for lib in input_dir.iterdir():
+    m = re.match(re_expr, lib.name)
+    if m:
+        _, lib_name, lib_version = m.groups()
+        lib_html = lib/"doxygen"/"html"
+        copy_library(lib_html, lib_name, lib_version)
+        # Handle gazebo->sim rename by making a copy into the sim directory
+        if lib_name == "gazebo":
+            copy_library(lib_html, "sim", lib_version)