Categorize tutorials list

tutorials.md.in

@@ -4,48 +4,25 @@ Welcome to the Gazebo @GZ_DESIGNATION_CAP@ tutorials. These tutorials
 will guide you through the process of understanding the capabilities of the
 Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 
+## Getting Started
 
-**Tutorials**
-
+* \subpage install "Installation": Install instructions.
 * \subpage terminology "Terminology": List of terms used across the documentation.
-* \subpage install "Install instructions": Install instructions.
-* \subpage createsystemplugins "Create System Plugins": Programmatically access simulation using C++ plugins.
-* \subpage rendering_plugins "Rendering plugins": Write plugins that use Gazebo Rendering on the server and client.
-* \subpage levels "Levels": Load entities on demand in large environments.
-* \subpage distributedsimulation "Distributed Simulation": Spread simulation across several processes.
-* \subpage resources "Finding resources": The different ways in which Gazebo looks for files.
-* \subpage entity_creation "Entity creation": Insert models or lights using services.
-* \subpage log "Logging": Record and play back time series of world state.
-* \subpage physics "Physics engines": Loading different physics engines.
-* \subpage light_config "Light config": Configure lights in the scene.
-* \subpage battery "Battery": Keep track of battery charge on robot models.
 * \subpage gui_config "GUI configuration": Customizing your layout.
 * \subpage server_config "Server configuration": Customizing what system plugins are loaded.
-* \subpage debugging "Debugging": Information about debugging Gazebo.
-* \subpage pointcloud "Converting a Point Cloud to a 3D Model": Turn point cloud data into 3D models for use in simulations.
-* \subpage meshtofuel "Importing a Mesh to Fuel": Build a model directory around a mesh so it can be added to the Gazebo Fuel app.
-* \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds.
-* \subpage detachablejoints "Detachable Joints": Creating models that start off rigidly attached and then get detached during simulation.
-* \subpage triggeredpublisher "Triggered Publisher": Using the TriggeredPublisher system to orchestrate actions in simulation.
-* \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation.
-* \subpage videorecorder "Video Recorder": Record videos from the 3D render window.
-* \subpage collada_world_exporter "Collada World Exporter": Export an entire world to a single Collada mesh.
-* \subpage underwater_vehicles "Underwater Vehicles": Understand how to simulate underwater vehicles.
-* \subpage particle_emitter "Particle emitter": Using particle emitters in simulation
-* \subpage blender_sdf_exporter "Blender SDF Exporter": Use a Blender script to export a model to the SDF format.
-* \subpage blender_distort_meshes "Blender mesh distortion": Use a Blender Python script to programmatically deform and distort meshes to customized extents.
-* \subpage blender_procedural_datasets "Generation of Procedural Datasets with Blender": Use Blender with a Python script to generate procedural datasets of SDF models.
-* \subpage model_and_optimize_meshes "Model and optimize meshes": Some recomendations when creating meshes in blender for simulations.
 * \subpage model_command "Model Command": Use the CLI to get information about the models in a simulation.
-* \subpage test_fixture "Test Fixture": Writing automated CI tests
-* \subpage model_photo_shoot "Model Photo Shoot" Taking perspective, top, front, and side pictures of a model.
-* \subpage spherical_coordinates "Spherical coordinates": Working with latitude and longitude
-* \subpage python_interfaces Python interfaces
-* \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server.
 * \subpage reset_simulation Reset simulation
+* \subpage resources "Finding resources": The different ways in which Gazebo looks for files.
+* \subpage debugging "Debugging": Information about debugging Gazebo.
+
+### GUI and rendering features
+
 * \subpage move_camera_to_model Move camera to model
+* \subpage model_photo_shoot "Model Photo Shoot" Taking perspective, top, front, and side pictures of a model.
+* \subpage videorecorder "Video Recorder": Record videos from the 3D render window.
+* \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server.
 
-**Migration from Gazebo classic**
+### Migration from Gazebo classic
 
 * \subpage migrationplugins "Plugins": Walk through the differences between writing plugins for Gazebo classic and Gazebo
 * \subpage migrationsdf "SDF": Migrating SDF files from Gazebo classic to Gazebo
@@ -57,6 +34,49 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 * \subpage migrationlinkapi "Link API": Guide on what Link C++ functions to call in Gazebo when migrating from Gazebo classic
 * \subpage ardupilot "Case Study": Migrating the ArduPilot ModelPlugin from Gazebo classic to Gazebo.
 
+## Intermediate
+
+* \subpage log "Logging": Record and play back time series of world state.
+* \subpage light_config "Light config": Configure lights in the scene.
+* \subpage levels "Levels": Load entities on demand in large environments.
+* \subpage python_interfaces Python interfaces
+
+### Specific systems and features
+
+* \subpage detachablejoints "Detachable Joints": Creating models that start off rigidly attached and then get detached during simulation.
+* \subpage triggeredpublisher "Triggered Publisher": Using the TriggeredPublisher system to orchestrate actions in simulation.
+* \subpage battery "Battery": Keep track of battery charge on robot models.
+* \subpage particle_emitter "Particle emitter": Using particle emitters in simulation
+* \subpage spherical_coordinates "Spherical coordinates": Working with latitude and longitude
+* \subpage underwater_vehicles "Underwater Vehicles": Understand how to simulate underwater vehicles.
+* \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation.
+
+## Advanced users
+
+* \subpage physics "Physics engines": Loading different physics engines.
+* \subpage entity_creation "Entity creation": Insert models or lights using services.
+* \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds.
+* \subpage distributedsimulation "Distributed Simulation": Spread simulation across several processes.
+
+## Developers
+
+* \subpage createsystemplugins "Create System Plugins": Programmatically access simulation using C++ plugins.
+* \subpage rendering_plugins "Rendering plugins": Write plugins that use Gazebo Rendering on the server and client.
+* \subpage test_fixture "Test Fixture": Writing automated CI tests
+
+## 3D modeling help
+
+* \subpage collada_world_exporter "Collada World Exporter": Export an entire world to a single Collada mesh.
+* \subpage meshtofuel "Importing a Mesh to Fuel": Build a model directory around a mesh so it can be added to the Gazebo Fuel app.
+* \subpage pointcloud "Converting a Point Cloud to a 3D Model": Turn point cloud data into 3D models for use in simulations.
+
+### Blender help
+
+* \subpage model_and_optimize_meshes "Model and optimize meshes in Blender": Some recomendations when creating meshes in Blender for simulations.
+* \subpage blender_sdf_exporter "Blender SDF Exporter": Use a Blender script to export a model to the SDF format.
+* \subpage blender_distort_meshes "Blender mesh distortion": Use a Blender Python script to programmatically deform and distort meshes to customized extents.
+* \subpage blender_procedural_datasets "Generation of Procedural Datasets with Blender": Use Blender with a Python script to generate procedural datasets of SDF models.
+
 ## License
 
 The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).

tutorials/gui_config.md

@@ -159,7 +159,7 @@ hand, we'll create it from the UI.
 
 1. Let's start loading the SDF world we created above, with the `<gui>` element back:
 
-`gz sim <path to>/fuel_preview.sdf`
+ `gz sim <path to>/fuel_preview.sdf`
 
 2. Now from the top-right menu, choose to add the "View Angle" plugin. This
  plugin has convenient buttons to change the camera angle, try them out!

tutorials/install.md

@@ -1,7 +1,5 @@
 \page install Installation
 
-# Install
-
 These instructions are for installing only Gazebo. If you're interested
 in using all the Gazebo libraries, not only Igniton Gazebo, check out this
 [Gazebo installation](https://gazebosim.org/docs/latest/install).
@@ -117,7 +115,7 @@ feature which hasn't been released yet.
  sudo make install
  ```
 
-# Documentation
+## Documentation
 
 API documentation and tutorials can be accessed at [https://gazebosim.org/libs/gazebo](https://gazebosim.org/libs/gazebo)
 
@@ -147,7 +145,7 @@ You can also generate the documentation from a clone of this repository by follo
  firefox doxygen/html/index.html
  ```
 
-# Testing
+## Testing
 
 Follow these steps to run tests and static code analysis in your clone of this repository.
 

tutorials/light_config.md

@@ -3,7 +3,7 @@
 This tutorial gives an introduction to Gazebo Sim's service `/world/<world name>/light_config`.
 This service will allow to modify lights in the scene.
 
-# Modifying lights
+## 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).
@@ -21,7 +21,7 @@ In this case we are creating random numbers to fill the diffuse and specular.
 
 \snippet examples/standalone/light_control/light_control.cc random numbers
 
-# Run the example
+## Run the example
 
 To run this example you should `cd` into `examples/standalone/light_control` and build the code:
 

tutorials/model_command.md

@@ -21,7 +21,6 @@ Open a new terminal and enter:
 
 And available models should be printed:
 
-
  Available models:
  - ground_plane
  - vehicle_blue

tutorials/model_photo_shoot.md

@@ -1,6 +1,6 @@
 \page model_photo_shoot Model Photo Shoot
 
-## Using the model photo shot plugin
+## Using the Model Photo Shoot plugin
 
 Gazebo offers a model photo taking tool that will take perspective,
 top, front, and both sides pictures of a model. You can test the demo world

tutorials/python_interfaces.md

@@ -1,8 +1,8 @@
 \page python_interfaces Python interfaces
 
-# Overview
+## Overview
 
-Gazebo provides a Python API to interact with world.
+Gazebo provides a Python API to interact with the world.
 
 For now, we provide a `TestFixture` class that allows to load a world file,
 step simulation and check entities and components.
@@ -40,7 +40,7 @@ fixture.finalize()
 server.run(True, 1000, False)
 ```
 
-# Run the example
+## Run the example
 
 In the
 [examples/scripts/python_api](https:/gazebosim/gz-sim/tree/gz-sim7/examples/scripts/python_api)

tutorials/reset_simulation.md

@@ -4,7 +4,7 @@ The Reset Gazebo transport API is exposed to allow resetting simulation to time
 It's possible to call this API using the command line or through the GUI.
 In addition to the API, we have also expanded the simulation system API with a Reset interface.
 
-# Reset interface
+## Reset interface
 
 System authors may now choose to implement the Reset interface to have a more intelligent
 reset process (avoiding reloading assets or regenerating scene graphs being the motivating examples).
@@ -13,7 +13,7 @@ The [physics](https:/gazebosim/gz-sim/blob/gz-sim7/src/systems/physi
 
 Following the tutorial \subpage createsystemplugins we should implement `ISystemReset` interface.
 
-# Transport API
+## Transport API
 
 To call the reset transport API we should call the service `/world/default/control` and fill the request message type
 `gz.msgs.WorldControl`, this service return a `gz.msgs.Boolean` with the status of the reset (true is everything was fine, false otherwise)
@@ -24,7 +24,7 @@ The `WorldControl` message now contains a reset field that we should filled if w
 gz service -s /world/default/control --reqtype gz.msgs.WorldControl --reptype gz.msgs.Boolean --timeout 3000 --req 'reset: {all: true}'
 ```
 
-# GUI
+## GUI
 
 We included a new button in the `World Control` plugin allowing to reset the simulation from the GUI
 

tutorials/underwater_vehicles.md

@@ -1,5 +1,6 @@
 \page underwater_vehicles Underwater vehicles
-# Simulating Autnomous Underwater Vehicles
+
+## Simulating Autnomous Underwater Vehicles
 
 Gazebo now supports basic simulation of underwater vehicles.
 This capability is based on the equations described in Fossen's ["Guidance and
@@ -10,14 +11,16 @@ guide you through the setup of the [MBARI Tethys](https://app.gazebosim.org/accu
 One can find the final sdf file for this tutorial in the
 `examples/worlds/auv_controls.sdf` file.
 
-# Understanding Hydrodynamic Forces
+## Understanding Hydrodynamic Forces
+
 The behaviour of a moving body through water is different from the behaviour of
 a ground based vehicle. In particular bodies moving underwater experience much
 more forces derived from drag, buoyancy and lift. The way these forces act on
 a body can be seen in the following diagram:
 ![force diagram](https://raw.githubusercontent.com/gazebosim/gz-sim/ign-gazebo5/tutorials/files/underwater/MBARI%20forces.png)
 
-# Setting up the buoyancy plugin
+## Setting up the buoyancy plugin
+
 The buoyancy plugin in Gazebo uses the collision mesh to calculate the volume
 of the vehicle. The calculated volume is used to determine the buoyancy force,
 which is then applied at the pose of the collision mesh in the link frame. Note
@@ -35,7 +38,9 @@ tag:
  <uniform_fluid_density>1000</uniform_fluid_density>
 </plugin>
 ```
-# Setting up the thrusters
+
+## Setting up the thrusters
+
 We need the vehicle to move, so we will be adding the `Thruster` plugin. The
 thruster plugin takes in a force and applies it along with calculating the desired
 rpm. Under the `<include>` or `<model>` tag add the following:
@@ -64,7 +69,8 @@ constant is normally determined by individual manufacturers. In this case we are
 using the Tethys's thrust coefficient. you may also build a test rig to measure
 your thruster's thrust coefficient.
 
-# Adding Hydrodynamic behaviour
+## Adding Hydrodynamic behaviour
+
 You may notice that the robot now keeps getting faster and faster. This is
 because there is no drag to oppose the thruster's force. We will be using
 Fossen's equations which describe the motion of a craft through the water for
@@ -97,7 +103,8 @@ name="gz::sim::systems::Hydrodynamics">
 </plugin>
 ```
 
-# Control surfaces
+## Control surfaces
+
 Just like aeroplanes, an underwater vehicle may also use fins for stability and
 control. Fortunately, Gazebo already has a version of the LiftDrag plugin. In
 this tutorial, we will simply add two liftdrag plugins to the rudder and
@@ -169,7 +176,7 @@ gz topic -t /model/tethys/joint/vertical_fins_joint/0/cmd_pos \
  -m gz.msgs.Double -p 'data: -0.17'
 ```
 
-# Testing the system out
+## Testing the system out
 
 To control the rudder of the craft run the following
 ```
@@ -183,7 +190,7 @@ gz topic -t /model/tethys/joint/propeller_joint/cmd_pos \
 ```
 The vehicle should move in a circle.
 
-# Ocean Currents
+## Ocean Currents
 
 When underwater, vehicles are often subject to ocean currents. The hydrodynamics
 plugin allows simulation of such currents. We can add a current simply by