Added documentation for usage of setup-gazebo

Signed-off-by: Saurabh Kamat <[email protected]>

Author: sauk2

index.yaml

@@ -28,6 +28,23 @@ pages:
         title: ROS 2 Gazebo Vendor Packages
         file: ros2_gz_vendor_pkgs.md
         description: Using ROS 2 Gazebo Vendor packages
+  - name: setup_gazebo_in_ci
+    title: Continuous Integration For Gazebo Packages
+    file: setup_gazebo_in_ci.md
+    description: Instruction on using setup-gazebo
+    children:
+      - name: setup_gazebo_in_ci_ubuntu
+        title: Ubuntu Runners
+        file: setup_gazebo_in_ci_ubuntu.md
+        description: Instruction on using setup-gazebo with Ubuntu
+      - name: setup_gazebo_in_ci_macos
+        title: macOS Runners
+        file: setup_gazebo_in_ci_macos.md
+        description: Instruction on using setup-gazebo with mscOS
+      - name: setup_gazebo_in_ci_windows
+        title: Windows Runners
+        file: setup_gazebo_in_ci_windows.md
+        description: Instruction on using setup-gazebo with Windows
   - name: gazebo_classic_migration
     title: Gazebo Classic Migration
     file: gazebo_classic_migration.md

setup_gazebo_in_ci.md

@@ -0,0 +1,28 @@
+# Setting up Gazebo in a Continuous Integration (CI) Pipeline
+
+Setting up a Gazebo environment in a Continuous Integration (CI) pipeline can often be a complex and time-consuming task.
+It typically involves installing various dependencies, managing repository keys, and ensuring platform compatibility with the Gazebo distribution.
+If done incorrectly, this can lead to unpredictable behaviors in CI due inconsistencies across environments.
+This section provides information on setting up a Gazebo in a continuous integration pipeline using the `setup-gazebo` GitHub Action to automate the entire process of configuring a Gazebo environment in a CI by taking care of everything, from handling dependencies to installing the desired Gazebo distribution.
+
+This action can also be used to install Gazebo alongside ROS 2 along with ROS-Gazebo bridge (`ros_gz`). It handles the installation of the correct version of Gazebo and `ros_gz` from all of all the recommended and supported combinations, along with possible combinations through ROS official binaries as ROS Gazebo vendor packages.
+
+The `setup-gazebo` GitHub Action can be found on the [Marketplace](https://github.com/marketplace/actions/setup-gazebo-environment) with its source code hosted at [github.com/gazebo-tooling/setup-gazebo](https://github.com/gazebo-tooling/setup-gazebo). Also check this [community post](https://community.gazebosim.org/t/introducing-the-setup-gazebo-github-action/3132) for more details.
+
+## Supported Gazebo Releases
+
+The action currently supports all the non-EOL Gazebo releases. See [releases](https://gazebosim.org/docs/all/releases/) for more information.
+
+* Citadel
+* Fortress
+* Garden
+* Harmonic
+* Ionic
+
+## Supported Platforms
+
+The `setup-gazebo` GitHub Action works on three platforms,
+
+* [Ubuntu](setup_gazebo_in_ci_ubuntu)
+* [macOS](setup_gazebo_in_ci_macos)
+* [Windows](setup_gazebo_in_ci_windows)

setup_gazebo_in_ci_macos.md

@@ -0,0 +1,35 @@
+# Using `setup-gazebo` with macOS Runners
+
+This section details the usage of `setup-gazebo` GitHub Action on macOS runners. The action can be directly run using GitHub hosted macOS runners, a full list of available runners can be found [here](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories).
+
+## Overview
+
+The `setup-gazebo` GitHub Action on macOS runners takes in the following parameters as input:
+
+* `required-gazebo-distributions`: A **required** parameter that specifies the Gazebo distribution to be installed. The allowed keywords are,
+  * `citadel`
+  * `fortress`
+  * `garden`
+  * `harmonic`
+  * `ionic`
+
+## Installing Gazebo on a macOS runner
+
+This workflow shows how to install Gazebo Ionic on a macOS worker using the Homebrew package manager which is installed by the action. To run, this action needs an input for `required-gazebo-distributions` parameter.
+
+```yaml
+  jobs:
+    test_gazebo:
+      runs-on: macos-13
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/[email protected]
+          with:
+            node-version: '20.x'
+        - name: 'Check Gazebo installation on MacOS runner'
+          uses: gazebo-tooling/[email protected]
+          with:
+            required-gazebo-distributions: 'ionic'
+        - name: 'Test Gazebo installation'
+          run: 'gz sim --versions'
+```