Create sections for navigation menu by azeey · Pull Request #662 · gazebosim/docs

azeey · 2025-12-20T05:57:47Z

🎉 New feature

Summary

Currently, the navigation menu on gazebosim.org/docs is a flat list and can be difficult to navigate. There also no clear organization between items that are tutorials vs how-to guildes vs reference, etc. This PR organizes the documents based on the diataxis framework.

To make all of this possible, the build script had to be modifed.

Navigation menu is now only defined in the index.yaml files in the versioned directories (e.g. jetty/index.yaml). The top level index.yaml no longer contains pages. This allows for more control over the order of items and organizing them into different sections.
Since the pages are now in the versioned directories, files that are common to all gazebo versions have been moved to the common directory. This is to make it explicit in the index.yaml files where these files are coming from. Otherwise, there it would be confusing since the common files are no longer peers of the index.yaml files that reference them. When referencing these files in index.yaml, the prefix common: has to be used now.
The build script adds functionality to add sections.
Pages without a file, but with children will be considered organizational elements and the appropriate file for sphinx is automatically generated.

TODO

Sections are only defined for jetty (so, only build_multiversion.py -r jetty works right now)
Define User and Developer personas
Update README

Preview

Checklist

Signed all commits for DCO
Updated documentation (as needed)
While waiting for a review on your PR, please help review another open pull request to support the maintainers
Was GenAI used to generate this PR? If so, make sure to add "Generated-by" to your commits. (See this policy for more info.)

Generated-by: Gemini 2.5

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by and Generated-by messages.

This also moves the `pages` entries from the root `index.yaml` to the `index.yaml` of the versioned directories. This allows more control over the navigation menu (order of elements) Generated-By: Gemini 2.5 Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

scpeters · 2026-03-27T21:06:56Z

conflicts

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

…to README Generated-By: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Generated-By: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Generated-by: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

azeey · 2026-04-03T02:54:46Z

This is ready for review

caguero

All looking good. I made a few inline comments.

My other suggestion is whether is worth to consolidate the "For Developers", "Reference" and "Migration Guides" sections in common or any other place that avoids repeating them over all yamls.

caguero · 2026-04-22T10:30:59Z

@@ -1,3 +1,5 @@
+# Gazebo Library How-To Guides


There seems to be now two top-level H1s in one document: Gazebo Library How-To Guides and Ignition Tutorials. I think this is inconsistent with the other distributions, where there's only one top-level section (except edifice, which has the same issue).

Made all the library_howto files uinform and used a MyST substitution instead of hardcoding the version numbers in 27343d8

caguero · 2026-04-22T10:31:19Z

@@ -1,3 +1,5 @@
+# Gazebo Library How-To Guides


There seems to be now two top-level H1s in one document: Gazebo Library How-To Guides and Ignition Tutorials. I think this is inconsistent with the other distributions, where there's only one top-level section (except dome, which has the same issue).

caguero · 2026-04-22T11:20:02Z

+            title: Release process
+            file: common:release.md
+            description: Release process overview.
+          - name: releases-instructions


Replace it with release_instructions? The generated URL looks more consistent with the other and clear in singular.

This would break the current URL though https://gazebosim.org/docs/jetty/releases-instructions/

caguero · 2026-04-22T11:30:10Z

+      - name: tutorials
+        title: Simulation Tutorials
+        children:
+          - name: spawn_urdf


The order of this tutorial isn't consistent. Sometimes appear at the top and sometimes at the bottom. Should we move it to the bottom for consistency? Check other distributions too.

The goal was to match the existing website. If you look at citadel/index.yaml in the main branch:

docs/citadel/index.yaml

Lines 54 to 92 in b696405

children:

- name: ros_integration

title: ROS Integration

file: ros_integration.md

description: This tutorial details how to interface with ROS, enabling the ability to use tools such as Rviz for robot or sensor visualization.

- name: ros2_integration

title: ROS 2 Integration

file: ros2_integration.md

- name: spawn_urdf

title: Spawn URDF

file: spawn_urdf.md

- name: gui

title: Understanding the GUI

file: GUI_tutorial.md

- name: manipulating_models

title: Manipulating Models

file: Manipulating_models.md

- name: fuel_insert

title: Model Insertion from Fuel

file: Model_insertion_fuel.md

- name: hotkeys

title: Keyboard Shortcuts

file: hotkeys.md

description: Ignition keyboard shortcuts

- name: building_robot

title: Building your own robot

file: building_robot.md

- name: moving_robot

title: Moving the robot

file: moving_robot.md

- name: sdf_worlds

title: SDF worlds

file: sdf_worlds.md

- name: sensors

title: Sensors

file: sensors.md

- name: actors

title: Actors

file: actors.md

spawn_urdf comes right after ros_integration and ros2_integration, which are now in the how-to. I opted to keep the order of the existing index.yaml wherever possible to keep changes to a minimum and to make it easier to review.

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Use MyST substitutions populated from top-level index.yaml to ensure uniformity and correctness across releases. Generated-By: Gemini 3.0 Pro Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Added a comment pointing to README.md for more information about the documentation structure and build process. Generated-By: Gemini 3.0 Pro Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Extracted common navigation sections to shared files in common/ and supported !include in build script and conf.py. Made all versions uniform by creating library_howtos.md for older releases. Generated-By: Gemini 3.0 Pro Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

azeey · 2026-04-28T03:52:01Z

All looking good. I made a few inline comments.

My other suggestion is whether is worth to consolidate the "For Developers", "Reference" and "Migration Guides" sections in common or any other place that avoids repeating them over all yamls.

Thanks for the suggestion. 2fe7ce3 extracts common navigation sections to shared files in common/ and uses !include directives in the index.yaml files. This still allows adding more items to a given section as is necessary in some cases (e.g. Fortress and earlier don't have a page for migrating from Ignition).

caguero

Just a few minor comments.

caguero · 2026-05-04T22:49:43Z

+* **Users**: For those who primarily run Gazebo using standard tools (like `gz
+sim`), edit SDFormat files, use existing plugins, and interact with running
+simulations from the outside — typically by publishing and subscribing to
+topics over Gazebo Transport or ROS."


Nit: Remove the traling quote (")?

caguero · 2026-05-04T22:52:32Z

+    with open(version_tmp_dir / "index.yaml") as f:
+        version_nav_yaml = yaml.safe_load(f)
+        version_nav_yaml['pages'] = flatten_navigation(version_nav_yaml['pages'])
+        if not version_nav_yaml or not version_nav_yaml.get("pages"):


Should this entire check appear before the previous line where we index with pages?

caguero · 2026-05-04T22:55:14Z

+    with open(map_path) as f:
+        source_manifest = json.load(f)
+
+    def yaml_include(loader, node):


This function seems duplicated as it already appeared in build_multiversion.py:29-37. Consider to refactor it.

caguero · 2026-05-04T22:56:49Z

+
+    yaml.SafeLoader.add_constructor('!include', yaml_include)
+
+    def flatten_navigation(nav_items):


This function seems duplicated as it already appeared in build_multiversion.py:40-54. Consider to refactor it.

caguero · 2026-05-04T23:00:32Z


+            # TODO(azeey) Document
+            if "file" in page:
+                file_path = page["file"].replace("common:", "")


Consider using .removeprefix instead of replace. I think we only want to replace a potential prefix.

caguero · 2026-05-04T23:01:18Z

    for page in nav_yaml_pages:
-        file_name_map[page["name"]] = f"{prefix}{page['file']}"
+        if "file" in page:
+            file_name_map[page["name"]] = page['file'].replace("common:", "")


Consider using .removeprefix instead of replace. I think we only want to replace a potential prefix.

Addisu Z. Taddese added 6 commits December 19, 2025 21:47

Move releasing and images to 'common'

eaf33cd

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Fix edit on github for references not included in the index

30781c3

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Get rid of combined_nav

af71bc8

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Add sections to the navigation menu

9b487fa

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Remove edit on github buttons on generated pages

a4d59d9

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

azeey added this to Core development Dec 20, 2025

github-actions Bot added 🌱 garden Gazebo Garden 🎵 harmonic Gazebo Harmonic 🏛️ ionic 🏢 edifice Ignition Edifice 🏯 fortress Ignition Fortress 🏰 citadel Ignition Citadel 📜 blueprint Ignition Blueprint 🔮 dome Ignition Dome 🪵 jetty labels Dec 20, 2025

github-project-automation Bot moved this to Inbox in Core development Dec 20, 2025

azeey requested review from caguero, iche033 and j-rivero December 20, 2025 05:58

iche033 mentioned this pull request Jan 22, 2026

Add bazel guide for maintainers #668

Open

azeey added 4 commits April 2, 2026 15:45

Merge remote-tracking branch 'origin/master' into common_files_menu

f2c7445

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

docs: add documentation structure and index.yaml configuration guide …

e03eac4

…to README Generated-By: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

docs: add user and developer workflow guidance to getting started page

cb8510a

Generated-By: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Apply changes to all releases

7c8ca79

Generated-by: Gemini 3.0 Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Merge remote-tracking branch 'origin/master' into common_files_menu

0d3784f

caguero reviewed Apr 22, 2026

View reviewed changes

Merge remote-tracking branch 'origin/master' into common_files_menu

0090769

azeey added 6 commits April 27, 2026 17:22

Address reviewer feedback

f066009

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Avoid hardcoding library links in library_howtos.md

27343d8

Use MyST substitutions populated from top-level index.yaml to ensure uniformity and correctness across releases. Generated-By: Gemini 3.0 Pro Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Address reviewer feedback

d9525b0

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Add pointer to README in index.yaml files

319e4c7

Added a comment pointing to README.md for more information about the documentation structure and build process. Generated-By: Gemini 3.0 Pro Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Fix trailing spaces

3b7164f

Signed-off-by: Addisu Z. Taddese <addisuzt@intrinsic.ai>

Merge remote-tracking branch 'origin/master' into common_files_menu

e788917

azeey requested a review from caguero April 30, 2026 20:18

caguero reviewed May 4, 2026

View reviewed changes

	children:
	- name: ros_integration
	title: ROS Integration
	file: ros_integration.md
	description: This tutorial details how to interface with ROS, enabling the ability to use tools such as Rviz for robot or sensor visualization.
	- name: ros2_integration
	title: ROS 2 Integration
	file: ros2_integration.md
	- name: spawn_urdf
	title: Spawn URDF
	file: spawn_urdf.md
	- name: gui
	title: Understanding the GUI
	file: GUI_tutorial.md
	- name: manipulating_models
	title: Manipulating Models
	file: Manipulating_models.md
	- name: fuel_insert
	title: Model Insertion from Fuel
	file: Model_insertion_fuel.md
	- name: hotkeys
	title: Keyboard Shortcuts
	file: hotkeys.md
	description: Ignition keyboard shortcuts
	- name: building_robot
	title: Building your own robot
	file: building_robot.md
	- name: moving_robot
	title: Moving the robot
	file: moving_robot.md
	- name: sdf_worlds
	title: SDF worlds
	file: sdf_worlds.md
	- name: sensors
	title: Sensors
	file: sensors.md
	- name: actors
	title: Actors
	file: actors.md


		yaml.SafeLoader.add_constructor('!include', yaml_include)

		def flatten_navigation(nav_items):

Conversation

azeey commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 New feature

Summary

TODO

Preview

Checklist

Uh oh!

scpeters commented Mar 27, 2026

Uh oh!

azeey commented Apr 3, 2026

Uh oh!

caguero left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

azeey commented Apr 28, 2026

Uh oh!

caguero left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

azeey commented Dec 20, 2025 •

edited

Loading

caguero left a comment •

edited

Loading