Fix broken / update ign links in tutorials (Harmonic) (#2107)

* fix broken link to API * use \ref for links. Revert common::Event link * make links local so that version updates automatically * update URLs to latest release versions, and ignition->gz namespace * fix migration tutorial titles * ref link for gz::gui::plugins, dependent on gz-gui PR#571 --------- Signed-off-by: Mabel Zhang <[email protected]>
gazebosim · Sep 14, 2023 · 294fddc · 294fddc
1 parent 2bef470
commit 294fddc
Show file tree

Hide file tree

Showing 19 changed files with 77 additions and 110 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -272,6 +272,7 @@ if (NOT APPLE)
      "${GZ-TRANSPORT_DOXYGEN_TAGFILE} = ${GZ-TRANSPORT_API_URL}"
      "${GZ-SENSORS_DOXYGEN_TAGFILE} = ${GZ-SENSORS_API_URL}"
      "${GZ-COMMON_DOXYGEN_TAGFILE} = ${GZ-COMMON_API_URL}"
+     "${GZ-GUI_DOXYGEN_TAGFILE} = ${GZ-GUI_API_URL}"
   )
 endif()
 

diff --git a/tutorials/entity_creation.md b/tutorials/entity_creation.md
@@ -58,11 +58,11 @@ gz service --list
 # Factory message
 
 To create new entities in the world we need to use the
-[gz::msgs::EntityFactory](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1EntityFactory__V.html)
+[gz::msgs::EntityFactory](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1EntityFactory.html)
 message to send a request to the create service.
 This message allows us to create entities from strings, files,
-[Models](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1Model.html),
-[Lights](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1Light.html) or even clone models.
+[Models](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1Model.html),
+[Lights](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1Light.html) or even clone models.
 This tutorial introduces how to create entities from SDF strings and light messages.
 
 ## Insert an entity based on a string
@@ -103,7 +103,7 @@ Or we can create an SDF string:
 \snippet examples/standalone/entity_creation/entity_creation.cc create light str
 
 Please check the API to know which fields are available in the
-[Light message](https://gazebosim.org/api/msgs/6.2/classignition_1_1msgs_1_1Light.html).
+[Light message](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1Light.html).
 There are three types of lights: Point, Directional and Spot.
 
 Finally we should call the same service `/world/<world_name>/create`:

diff --git a/tutorials/gui_config.md b/tutorials/gui_config.md
@@ -3,7 +3,7 @@
 Gazebo Sim's graphical user interface is powered by
 [Gazebo GUI](https://gazebosim.org/libs/gui). Therefore, Gazebo Sim's
 GUI layout can be defined in
-[Gazebo GUI configuration files](https://gazebosim.org/api/gui/2.1/config.html).
+[Gazebo GUI configuration files](https://gazebosim.org/api/gui/8/config.html).
 These are XML files that describe what plugins to be loaded and with what
 settings.
 

diff --git a/tutorials/light_config.md b/tutorials/light_config.md
@@ -6,7 +6,7 @@ This service will allow to modify lights in the scene.
 ## Modifying lights
 
 To modify lights inside the scene we need to use the service `/world/<world name>/light_config` and
-fill the message [`gz::msgs::Light`](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1Light.html).
+fill the message [`gz::msgs::Light`](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1Light.html).
 In particular this example modifies the point light that we introduced with the function `createLight()`.
 
 \snippet examples/standalone/light_control/light_control.cc create light

diff --git a/tutorials/log.md b/tutorials/log.md
@@ -8,7 +8,7 @@ Gazebo records two types of information to files:
     * Always recorded
 * Simulation state
     * Entity poses, insertion and deletion
-    * Logged to an [Gazebo Transport `state.tlog` file](https://gazebosim.org/api/transport/7.0/logging.html)
+    * Logged to an [Gazebo Transport `state.tlog` file](https://gazebosim.org/api/transport/13/logging.html)
     * Recording must be enabled from the command line or the C++ API
     * Can be played back using the command line or the C++ API
 
@@ -42,7 +42,7 @@ Other options for recording:
 ### From C++ API
 
 All features available through the command line are also available through
-[gz::sim::ServerConfig](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1ServerConfig.html).
+\ref gz::sim::ServerConfig.
 When instantiating a server programmatically, logging options can be passed
 to the constructor, for example:
 

diff --git a/tutorials/migrating_ardupilot_plugin.md b/tutorials/migrating_ardupilot_plugin.md
@@ -1,6 +1,4 @@
-\page ardupilot
-
-# Case study: migrating the ArduPilot ModelPlugin from Gazebo classic to Gazebo
+\page ardupilot Case study: migrating the ArduPilot ModelPlugin from Gazebo classic to Gazebo
 
 A variety of changes are required when migrating a plugin from Gazebo classic
 to Gazebo. In this tutorial we offer as a case

diff --git a/tutorials/migration_actor_api.md b/tutorials/migration_actor_api.md
@@ -1,6 +1,4 @@
-\page migrationactorapi
-
-# Migration from Gazebo-classic: Actor API
+\page migrationactorapi Migration from Gazebo-classic: Actor API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -34,16 +32,13 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [gz/sim/Actor.hh](https://gazebosim.org/api/gazebo/7/Actor_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/7/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/7/SdfEntityCreator_8hh.html)
-* [gz/sim/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Actor.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly.
-
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
 
 As an example the `Actor::Pose()` is a convienient function for querying the `Pose` component from the `EntityComponentManager`, i.e.
 

diff --git a/tutorials/migration_joint_api.md b/tutorials/migration_joint_api.md
@@ -1,6 +1,4 @@
-\page migrationjointapi
-
-# Migration from Gazebo-classic: Joint API
+\page migrationjointapi Migration from Gazebo-classic: Joint API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -32,15 +30,13 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [gz/sim/Joint.hh](https://gazebosim.org/api/gazebo/7/Joint_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/7/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/7/SdfEntityCreator_8hh.html)
-* [gz/sim/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Joint.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
 
 As an example the `Join::Pose()` is a convienient function for querying the `Pose` component from the `EntityComponentManager`, i.e.
 

diff --git a/tutorials/migration_light_api.md b/tutorials/migration_light_api.md
@@ -1,6 +1,4 @@
-\page migrationlightapi
-
-# Migration from Gazebo-classic: Light API
+\page migrationlightapi Migration from Gazebo-classic: Light API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -29,15 +27,13 @@ In Gazebo, the light APIs has been consolidated into a single Light class with
 some of generic functions available through other utility / core classes.
 You'll find the APIs below on the following headers:
 
-* [gz/sim/Light.hh](https://gazebosim.org/api/gazebo/7/Light_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/7/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/7/SdfEntityCreator_8hh.html)
-* [gz/sim/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Light.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
 
 As an example the `Light::Pose()` is a convienient function for querying the `Pose` component from the `EntityComponentManager`, i.e.
 

diff --git a/tutorials/migration_link_api.md b/tutorials/migration_link_api.md
@@ -1,6 +1,4 @@
-\page migrationlinkapi
-
-# Migration from Gazebo-classic: Link API
+\page migrationlinkapi Migration from Gazebo-classic: Link API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -34,15 +32,14 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [gz/sim/Link.hh](https://gazebosim.org/api/gazebo/7/Link_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/7/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/7/SdfEntityCreator_8hh.html)
-* [gz/sim/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Link.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly. The functions presented here exist for convenience and readability.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
+The functions presented here exist for convenience and readability.
 
 ### Properties
 

diff --git a/tutorials/migration_model_api.md b/tutorials/migration_model_api.md
@@ -1,6 +1,4 @@
-\page migrationmodelapi
-
-# Migration from Gazebo-classic: Model API
+\page migrationmodelapi Migration from Gazebo-classic: Model API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -34,15 +32,14 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [gz/sim/Model.hh](https://gazebosim.org/api/gazebo/3.3/Model_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/3.3/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/3.3/SdfEntityCreator_8hh.html)
-* [gz/sim/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/3.3/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Model.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/3.3/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly. The functions presented here exist for convenience and readability.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
+The functions presented here exist for convenience and readability.
 
 ### Properties
 

diff --git a/tutorials/migration_plugins.md b/tutorials/migration_plugins.md
@@ -1,6 +1,4 @@
-\page migrationplugins
-
-# Migration from Gazebo Classic: Plugins
+\page migrationplugins Migration from Gazebo Classic: Plugins
 
 Gazebo Classic supports
 [6 different C++ plugin types](http://gazebosim.org/tutorials?tut=plugins_hello_world&cat=write_plugin),

diff --git a/tutorials/migration_sdf.md b/tutorials/migration_sdf.md
@@ -1,6 +1,4 @@
-\page migrationsdf
-
-# Migration from Gazebo classic: SDF
+\page migrationsdf Migration from Gazebo classic: SDF
 
 Both Gazebo classic and Gazebo support [SDF](http://sdformat.org/)
 files to describe the simulation to be loaded. An SDF file defines the world

diff --git a/tutorials/migration_sensor_api.md b/tutorials/migration_sensor_api.md
@@ -1,6 +1,4 @@
-\page migrationsensorapi
-
-# Migration from Gazebo-classic: Sensor API
+\page migrationsensorapi Migration from Gazebo-classic: Sensor API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -32,15 +30,13 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [ignition/gazebo/Sensor.hh](https://gazebosim.org/api/gazebo/6/Sensor_8hh.html)
-* [ignition/gazebo/Util.hh](https://gazebosim.org/api/gazebo/6/Util_8hh.html)
-* [ignition/gazebo/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/6/SdfEntityCreator_8hh.html)
-* [ignition/gazebo/EntityComponentManager.hh](https://gazebosim.org/api/gazebo/6/classignition_1_1gazebo_1_1EntityComponentManager.html)
+* \ref gz/sim/Sensor.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/6/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
 
 As an example the `Sensor::Pose()` is a convienient function for querying the `Pose` component from the `EntityComponentManager`, i.e.
 

diff --git a/tutorials/migration_world_api.md b/tutorials/migration_world_api.md
@@ -1,6 +1,4 @@
-\page migrationworldapi
-
-# Migration from Gazebo-classic: World API
+\page migrationworldapi Migration from Gazebo-classic: World API
 
 When migrating plugins from Gazebo-classic to Gazebo, developers will
 notice that the C++ APIs for both simulators are quite different. Be sure to
@@ -34,14 +32,14 @@ can be divided in these categories:
 
 You'll find the Gazebo APIs below on the following headers:
 
-* [gz/sim/World.hh](https://gazebosim.org/api/gazebo/3.3/World_8hh.html)
-* [gz/sim/Util.hh](https://gazebosim.org/api/gazebo/3.3/Util_8hh.html)
-* [gz/sim/SdfEntityCreator.hh](https://gazebosim.org/api/gazebo/3.3/SdfEntityCreator_8hh.html)
+* \ref gz/sim/World.hh
+* \ref gz/sim/Util.hh
+* \ref gz/sim/SdfEntityCreator.hh
+* \ref gz/sim/EntityComponentManager.hh
 
 It's worth remembering that most of this functionality can be performed using
-the
-[EntityComponentManager](https://gazebosim.org/api/gazebo/3.3/classignition_1_1gazebo_1_1EntityComponentManager.html)
-directly. The functions presented here exist for convenience and readability.
+the \ref gz::sim::EntityComponentManager "EntityComponentManager" directly.
+The functions presented here exist for convenience and readability.
 
 ### Properties
 

diff --git a/tutorials/physics.md b/tutorials/physics.md
@@ -10,7 +10,7 @@ by default.
 
 Downstream developers may also integrate other physics engines by creating new
 Gazebo Physics engine plugins. See
-[Gazebo Physics](https://gazebosim.org/api/physics/2.0/tutorials.html)'s
+[Gazebo Physics](https://gazebosim.org/api/physics/7/tutorials.html)'s
 tutorials to learn how to integrate a new engine.
 
 ## How Gazebo finds engines
@@ -79,7 +79,7 @@ To use an existing alternative engine (e.g. Bullet Featherstone)
 ### From C++ API
 
 All features available through the command line are also available through
-[gz::sim::ServerConfig](https://gazebosim.org/api/gazebo/7/classignition_1_1gazebo_1_1ServerConfig.html).
+\ref gz::sim::ServerConfig.
 When instantiating a server programmatically, a physics engine can be passed
 to the constructor, for example:
 

diff --git a/tutorials/rendering_plugins.md b/tutorials/rendering_plugins.md
@@ -4,7 +4,7 @@ This tutorial will go over how to write Gazebo plugins that alter the
 3D scene's visual appearance using Gazebo Rendering APIs.
 
 This is not to be confused with integrating a new rendering engine. See
-[How to write your own rendering engine plugin](https://gazebosim.org/api/rendering/4.2/renderingplugin.html)
+[How to write your own rendering engine plugin](https://gazebosim.org/api/rendering/8/renderingplugin.html)
 for that.
 
 This tutorial will go over a couple of example plugins that are located at
@@ -45,8 +45,7 @@ To interact with the server-side scene, you'll need to write an
 See [Create System Plugins](createsystemplugins.html).
 
 To interact with the client-side scene, you'll need to write an
-[gz::gui::Plugin](https://gazebosim.org/api/gui/4.1/classignition_1_1gui_1_1Plugin.html),
-or a more specialized `gz::sim::GuiSystem`
+\ref gz::gui::Plugin, or a more specialized `gz::sim::GuiSystem`
 if you need to access entities and components.
 See the [GUI system plugin example](https://github.com/gazebosim/gz-sim/tree/main/examples/plugin/gui_system_plugin).
 
@@ -71,8 +70,7 @@ different for each plugin type.
 
 ### Render events on the GUI
 
-The GUI plugin will need to listen to
-[gz::gui::events::Render](https://gazebosim.org/api/gui/4.1/classignition_1_1gui_1_1events_1_1Render.html)
+The GUI plugin will need to listen to \ref gz::gui::events::Render
 events. Here's how to do it:
 
 1. Include the GUI events header: