docs

Gazebo Documentation

This repository contains documentation about Gazebo that does not pertain to a specific Gazebo library. An example would be installation instructions for an Gazebo release. The documentation contained in this repository can be view at https://gazebosim.org/docs.

Each Gazebo library maintains documentation and tutorials that are scoped to the features and capabilities of the library itself. The documentation for a library can be found under the API Reference section of https://gazebosim.org/docs.

Documentation Structure

The documentation is organized by Gazebo release version, with shared files located in a root-level common directory.

Repository Layout

• common/: Contains markdown files and folders that are shared across all Gazebo releases (e.g., installation overviews, architecture guides, governance documents, etc.).
• <release_name>/ (e.g., jetty/): Contains markdown files specific to a particular release and its specific index.yaml.

Release Navigation Menu (index.yaml)

Navigation menus are defined per-release in the release directory’s index.yaml (e.g., jetty/index.yaml). The top-level index.yaml only contains global release metadata and library information, not navigation definitions.

Organizing Pages with Sections

The pages key in the release index.yaml defines the menu hierarchy using the section key to group related items.

Example:

pages:
  - section: Get Started
    children:
      - name: getstarted
        title: Get Started
        file: common:get_started.md
      - name: release_notes
        title: Release Notes
        file: release_notes.md

Shared Files Prefix (common:)

To reference a file from the root-level common directory in a release-specific index.yaml, use the common: prefix in the file attribute.

- name: getstarted
  title: Get Started
  file: common:get_started.md

Files without the prefix are assumed to be relative to the release directory.

Reusing Common Navigation Items (!include)

To avoid duplication across versioned index.yaml files, you can use the !include tag to include shared lists of navigation items from the common/ directory.

Example:

- section: Reference
  children:
    - !include common/nav_reference.yaml
    - name: release_notes
      title: Release Notes
      file: release_notes.md

The build script will resolve the !include tag and flatten the list, effectively merging the shared items with any release-specific items listed before or after it.

Organizational Elements

If an entry in index.yaml has children but no file entry, it is considered an organizational element. The build script will automatically create a placeholder page for Sphinx to group the children under.

Main docs

The documentation in this repository is built using Sphinx. To build, you need to install the following:

• python virtualenv

Create the virtual env and activate it:

python3 -m venv .venv
source .venv/bin/activate

Then install the necessary dependencies:

pip install -r requirements.txt

python3 build_multiversion.py

This will build all the documentation for all versions of Gazebo. You can preview the result locally by running an HTTP server on the output directory .build. For example:

python3 -m http.server 8000 -d .build

This will serve the website on http://localhost:8000

For quicker iteration, you can build the documentation for a subset of Gazebo versions. To build harmonic and jetty:

python3 build_multiversion.py --release harmonic jetty

Spell checking

The Markdown documentation is spell-checked with codespell, run by the GitHub Actions workflow .github/workflows/codespell.yml.

For configuration, how to run the check locally, and how to add words, see .codespell/README.md.

Library docs

Instructions on how to update all of the library docs is contained in the tools/build_docs.sh script.