Reorganize and add more context to Gazebo migration guides (#480)

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

gazebo_classic_migration.md

@@ -0,0 +1,43 @@
+# Gazebo Classic Migration
+
+Gazebo was started in 2002. After over 15 years of development it was time for a
+significant upgrade and modernization. This upgrade also provided the
+opportunity to move away from a monolithic architecture to a collection of
+loosely coupled libraries.
+
+These collection of libraries make up the new Gazebo. As a convention we refer
+to older versions of Gazebo, those with release numbers like Gazebo 9 and Gazebo
+11 as "Gazebo Classic". Newer versions of Gazebo, formerly called "Ignition",
+with lettered releases names like Harmonic, are referred to as just "Gazebo".
+
+:::{tip}
+
+Since the name of the project has gone through two major changes, we highly
+recommend you read the [history](https://gazebosim.org/about) of the project as
+well as our
+[community post](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356) to
+have a better understanding of the terminology used on this website.
+
+:::
+
+Here you'll find guides and resources for migrating existing Gazebo Classic
+projects to the new Gazebo.
+
+- [Migrating ROS 2 packages that use Gazebo Classic](migrating_gazebo_classic_ros2_packages)
+- [Installing Gazebo11 side by side with new Gazebo](install_gz11_side_by_side)
+- Migration from Gazebo Classic: Plugins -
+  [Fortress](https://gazebosim.org/api/gazebo/6/migrationplugins.html) |
+  [Harmonic](https://gazebosim.org/api/sim/8/migrationplugins.html)
+- Migration from Gazebo classic: SDF -
+  [Fortress](https://gazebosim.org/api/gazebo/6/migrationsdf.html) |
+  [Harmonic](https://gazebosim.org/api/sim/8/migrationsdf.html)
+- Case study: migrating the ArduPilot ModelPlugin from Gazebo classic to
+  Gazebo - [Fortress](https://gazebosim.org/api/gazebo/6/ardupilot.html) |
+  [Harmonic](https://gazebosim.org/api/sim/8/ardupilot.html)
+- [Basic description of SDF worlds](sdf_worlds)
+- [Feature Comparison with Gazebo Classic](comparison)
+- [Documentation for ros_gz](ros2_integration)
+- List of Systems (plugins):
+  [Fortress](https://gazebosim.org/api/gazebo/6/namespaceignition_1_1gazebo_1_1systems.html)
+  |
+  [Harmonic](https://gazebosim.org/api/sim/8/namespacegz_1_1sim_1_1systems.html)

index.yaml

@@ -28,14 +28,19 @@ pages:
         title: ROS 2 Gazebo Vendor Packages
         file: ros2_gz_vendor_pkgs.md
         description: Using ROS 2 Gazebo Vendor packages
-  - name: install_gz11_side_by_side
-    title: Installing Gazebo11 side by side with new Gazebo
-    file: install_gz11_side_by_side.md
-    description: How to install gazebo11 and new Gazebo together
-  - name: migrating_gazebo_classic_ros2_packages
-    title: Migration from ROS 2 Gazebo Classic
-    file: migrating_gazebo_classic_ros2_packages.md
-    description: A tutorial on how to migrate a ROS 2 package that uses Gazebo Classic to the new Gazebo
+  - name: gazebo_classic_migration
+    title: Gazebo Classic Migration
+    file: gazebo_classic_migration.md
+    description: Guides for migrating from Gazebo Classic to the new Gazebo
+    children:
+    - name: install_gz11_side_by_side
+      title: Installing Gazebo11 side by side with new Gazebo
+      file: install_gz11_side_by_side.md
+      description: How to install gazebo11 and new Gazebo together
+    - name: migrating_gazebo_classic_ros2_packages
+      title: Migration from ROS 2 Gazebo Classic
+      file: migrating_gazebo_classic_ros2_packages.md
+      description: A tutorial on how to migrate a ROS 2 package that uses Gazebo Classic to the new Gazebo
   - name: roadmap
     title: Roadmap
     file: roadmap.md

migrating_gazebo_classic_ros2_packages.md

@@ -703,22 +703,7 @@ tutorial. For reference, those files have also been migrated in
 ## Migrating other files in turtlebot3_gazebo
 
 This tutorial does not cover all aspects of migrating models and launch files
-from Gazebo classic. The following is a list of useful resources that cover
-other aspects, such as migrating Gazebo Classic plugins, materials and textures.
-
-- Migration from Gazebo Classic: Plugins -
-  [Fortress](https://gazebosim.org/api/gazebo/6/migrationplugins.html) |
-  [Harmonic](https://gazebosim.org/api/sim/8/migrationplugins.html)
-- Migration from Gazebo classic: SDF -
-  [Fortress](https://gazebosim.org/api/gazebo/6/migrationsdf.html) |
-  [Harmonic](https://gazebosim.org/api/sim/8/migrationsdf.html)
-- Case study: migrating the ArduPilot ModelPlugin from Gazebo classic to
-  Gazebo - [Fortress](https://gazebosim.org/api/gazebo/6/ardupilot.html) |
-  [Harmonic](https://gazebosim.org/api/sim/8/ardupilot.html)
-- [Basic description of SDF worlds](sdf_worlds)
-- [Feature Comparison with Gazebo Classic](comparison)
-- [Documentation for ros_gz](ros2_integration)
-- List of Systems (plugins):
-  [Fortress](https://gazebosim.org/api/gazebo/6/namespaceignition_1_1gazebo_1_1systems.html)
-  |
-  [Harmonic](https://gazebosim.org/api/sim/8/namespacegz_1_1sim_1_1systems.html)
+from Gazebo classic. Please see the
+[Gazebo Classic Migration](gazebo_classic_migration) document for more resources
+that help with migrating other aspects, such as Gazebo Classic plugins,
+materials and textures.