Merge branch 'master' into scpeters/ci_matching_branch

.github/workflows/deploy.yml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+name: Deploy Website and Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build_website:
+    runs-on: ubuntu-latest
+    steps:
+      # Build website from gazebosim-web-frontend
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: gazebo-web/gazebosim-web-frontend
+          ref: main
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Install Website dependencies
+        run: npm ci
+      - name: Build Website
+        run: npm run build -- --base-href "${{ steps.pages.outputs.base_url }}/"
+      # Upload the artifact for local preview
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: website
+          path: dist
+
+      # Build Docs
+  build_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+      - name: Install Docs dependencies
+        run: pip install -r requirements.txt
+      - name: Build Docs
+        run: python build_multiversion.py --pointers --libs --output_dir .build
+        env:
+          GZ_DEPLOY_URL: "${{ steps.pages.outputs.base_url }}"
+
+      # Upload the artifact for local preview
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: .build
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [build_website, build_docs]
+    permissions:
+      contents: write
+    # Allow only one concurrent deployment between this and the nightly-upload workflow.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - name: Upload merged
+        uses: actions/upload-artifact@v4
+        with:
+          name: website-docs-merged
+          path: ./
+      - name: Commit
+        uses: peaceiris/actions-gh-pages@v4
+        # The workflow upto this point is good for generating a preview,
+        # but only commit to deploy if we are on the master branch (not a pull request).
+        if: github.ref == 'refs/heads/master'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./
+          keep_files: true

.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,29 +7,81 @@ 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:
+      contents: write
+    # Allow only one concurrent deployment between this and the deploy workflow.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
-    - name: Setup aws cli
-      run: |
-        sudo apt-get update &&
-        sudo apt-get install curl &&
-        curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" &&
-        unzip awscliv2.zip &&
-        sudo ./aws/install --update &&
-        aws --version
-    - 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: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-    - name: Invalidate Cloudfront distribution
-      run: |
-        aws configure set aws_access_key_id ${{ secrets.AWS_ACCESS_KEY_ID }} &&
-        aws configure set aws_secret_access_key ${{ secrets.AWS_SECRET_ACCESS_KEY }} &&
-        aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} --paths '/*' --region us-east-1
+      uses: actions/checkout@v4
+    - 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: Commit
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./.api-out
+        destination_dir: api
+        keep_files: true

.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:

.gitignore

@@ -0,0 +1,3 @@
+.build
+.tmp
+.venv

README.md

@@ -15,9 +15,45 @@ found under the `API Reference` section of [https://gazebosim.org/docs](https://
 
 ## Main docs
 
-The documentation in this repository is updated whenever the
-[gazebosim-web-backend](https://github.com/gazebo-web/gazebosim-web-backend),
-is deployed. The gazebosim-web-backend webserver maintains a clone of this repository, and serves the markdown pages to https://gazebosim.org/docs.
+The documentation in this repository is built using [Sphinx](https://www.sphinx-doc.org/).
+To build, you need to install the following:
+
+* python virtualenv
+
+Create the virtual env and activate it:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Then install the necessary dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+```bash
+python3 build_multiversion.py
+```
+
+This will build all the documentation for all versions of Gazebo.
+You can preview the result locally by running an HTTP server on
+the output directory `.build`. For example:
+
+```bash
+python3 -m http.server 8000 -d .build
+
+```
+
+This will serve the website on <http://localhost:8000>
+
+For quicker iteration, you can build the documentation for a subset
+of Gazebo versions. To build `garden` and `harmonic`:
+
+```bash
+python3 build_multiversion.py --release garden harmonic
+```
 
 ## Library docs