mkdocs.yml

---
copyright: Copyright © 2024 - 2030 AirLab CMU
docs_dir: .
site_name: AirStack
site_description: >-
  AirStack is an open-source ROS 2 autonomy stack for aerial robots from the
  AirLab at Carnegie Mellon University — simulation, ground control, and
  layered onboard autonomy that launch as one system.
site_dir: ../site
site_url: "https://docs.theairlab.org/docs/" # Trailing slash is recommended
exclude_docs: |
  # The repo README is GitHub-facing; the site's home page is docs/index.md,
  # and same-dir would otherwise collide on the root URL. Patterns are
  # gitignore-style: the leading slash anchors this to the repo root only —
  # a bare README.md would exclude every package/tests/osmo README the nav
  # serves as pages.
  /README.md
  **/ros_ws/build
  **/docker/Foxglove
  **/ros_ws/install
  **/kit-app-template/**
  **/isaac_sim_data/**
  # Downloaded AirSim UE4 scene binaries (fetched by assets/scenes/fetch_scene.sh)
  # and environments: multi-GB, gitignored, never doc content. Without this the
  # same-dir plugin copies them into every site build (~15 GB per build).
  simulation/ms-airsim/assets/scenes/**
  simulation/ms-airsim/environments/**
  # Fetched module checkouts (RFC #379 §9): the docs deploy workflows clone the
  # registry index + each registered module repo into the gitignored modules/
  # dir. Their content is linked from docs/modules/ (generated by
  # tools/gen_docs_catalog.py), never embedded as site pages this phase — so
  # exclude the checkouts and their overlay symlinks entirely.
  modules/**
  robot/ros_ws/src/modules/**
  simulation/isaac-sim/launch_scripts/modules/**
  # Dot-prefixed dirs (stacks/.external, .airstack) are already skipped by
  # MkDocs' default dotfile rule; listed here to keep that intent explicit.
  .airstack/**
  stacks/.external/**
extra:
  version:
    provider: mike
  generator: false
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/castacks
    - icon: fontawesome/brands/x-twitter
      link: https://x.com/airlabcmu
extra_css:
  - stylesheets/extra.css
# Trim the Release Notes page to the section matching the .env VERSION at
# build time, so each mike-deployed docs version shows only its own notes.
hooks:
  - docs/hooks/release_notes_current_version.py
  # Give the version-root redirect stub (/X.Y/ -> docs/) a real title and
  # Open Graph tags so shared links preview properly (Slack, WhatsApp, ...).
  - docs/hooks/social_meta_redirect_stub.py
markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.magiclink
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - toc:
      permalink: true
nav:
  - Home: docs/index.md
  - Beginner Tutorials:
      - Get AirStack Flying: docs/getting_started/index.md
      - Fly a Mission from the GCS: docs/getting_started/fly_a_mission.md
      - Change a Parameter: docs/getting_started/change_a_parameter.md
      - Modular AirStack Walkthrough: docs/getting_started/modular_airstack.md
      - Write Your First Module: docs/getting_started/first_module.md
      - Your First Fleet: docs/getting_started/first_fleet.md
      - Build and Fly Your Own Scene: docs/getting_started/build_your_own_scene.md
      - Deploy to Hardware: docs/real_world/deploying_to_hardware.md
      - What Next: docs/getting_started/tutorials_reference.md
  - Concepts:
      - Key Concepts: docs/development/beginner/key_concepts.md
      - System Architecture: docs/robot/autonomy/system_architecture.md
      - Modular AirStack:
          - Modules: docs/development/modules.md
          - Stacks: docs/development/stacks.md
          - Fleets: docs/development/fleets.md
      - Robot Identity: docs/robot/docker/robot_identity.md
      - Simulation Platforms:
          - Overview: docs/simulation/index.md
          - Isaac Sim: docs/simulation/isaac_sim/index.md
          - Pegasus Extension: docs/simulation/isaac_sim/pegasus_scene_setup.md
          - Microsoft AirSim (legacy): docs/simulation/ms-airsim/index.md
          - Simple Sim: docs/simulation/simple_sim/index.md
      - Ground Control Station: docs/gcs/index.md
      - CI/CD Architecture: docs/development/intermediate/testing/ci_cd.md
      - CLI Architecture: docs/development/advanced/airstack-cli/architecture.md
      - Frame Conventions: docs/development/intermediate/frame_conventions.md
  - How-to Guides:
      - Overview: docs/development/index.md
      - Development Environment:
          - Setup: docs/development/beginner/development_environment.md
          - VSCode & Debugging: docs/development/beginner/vscode/vscode_debug.md
          - Fork Your Own Project: docs/development/beginner/fork_your_own_project.md
          - Remote Development on OSMO: docs/tutorials/airstack_on_osmo.md
      - Docker & Builds:
          - Docker Workflow: docs/development/beginner/airstack-cli/docker_usage.md
          - Build Profiles: docs/development/intermediate/docker-build-profiles.md
      - Simulation:
          - Scenes: docs/simulation/scenes.md
          - Isaac Sim Container Workflows: docs/simulation/isaac_sim/container_workflows.md
          - Spawning Drones: docs/simulation/isaac_sim/spawning_drones.md
          - Overhead Camera: docs/simulation/isaac_sim/overhead_camera.md
          - Gimbal: docs/robot/autonomy/sensors/gimbal.md
          - Export Stages from Unreal: docs/simulation/isaac_sim/export_stages_from_unreal.md
      - Autonomy:
          - Add a State Estimator: docs/robot/autonomy/perception/adding_a_state_estimator.md
          - Add a World Model and Planner: docs/robot/autonomy/adding_a_world_model_and_planner.md
          - Add a Controller: docs/robot/autonomy/adding_a_controller.md
          - Create a Coordination Algorithm: docs/robot/autonomy/coordination/creating_coordination_algorithms.md
          - Coordination Payloads: docs/robot/autonomy/coordination/payloads.md
          - Integration Checklist: docs/robot/autonomy/integration_checklist.md
      - GCS Operation:
          - Waypoints & Geofences: docs/gcs/waypoints_and_geofences.md
          - Foxglove Visualization: docs/gcs/foxglove.md
          - Extending the Visualizer: docs/gcs/extending_foxglove.md
          - Operating the GCS: docs/gcs/usage/user_interface.md
      - Robot & Field:
          - Overview: docs/real_world/index.md
          - Install on Hardware: docs/real_world/installation/index.md
          - Add a Vehicle or Platform: docs/development/adding_a_vehicle.md
          - HITL Testing: docs/real_world/HITL/index.md
          - Data Offloading: docs/real_world/data_offloading/index.md
          - Data Offloading (DIY patterns): docs/robot/logging/data_offloading.md
          - Logging: docs/robot/logging/index.md
          - ROS Bags: docs/robot/logging/rosbags.md
      - Modules & Stacks:
          - Create a Custom Stack: docs/development/creating_a_stack.md
          - Module CI: docs/development/module_ci.md
      - Testing:
          - Overview: docs/development/intermediate/testing/index.md
          - Unit Testing: docs/development/intermediate/testing/unit_testing.md
          - End-to-End Testing: docs/development/intermediate/testing/end_to_end_testing.md
          - Using CI: docs/development/intermediate/testing/using_ci.md
      - Contributing:
          - Contributing Guide: docs/development/intermediate/contributing.md
          - Documentation Guide: docs/development/intermediate/documentation.md
          - Feature Notebook: docs/development/intermediate/feature_notebook.md
          - Working with Coding Agents: docs/development/working_with_coding_agents.md
          - Extending the CLI: docs/development/advanced/airstack-cli/extending.md
  - Reference:
      - CLI: docs/development/beginner/airstack-cli/index.md
      - Configuration:
          - Robot Configuration: docs/robot/configuration/index.md
          - Environment Variables: docs/robot/configuration/environment_variables.md
          - Vehicle Config Schema: config/vehicles/README.md
          - Local Calibration: config/local/README.md
          - Static Transforms: docs/robot/static_transforms/index.md
      - Interfaces:
          - Interface Conventions Spec: docs/robot/autonomy/interface_conventions.md
          - Tasks and Task Executors: docs/robot/autonomy/tasks.md
          - DDS Router: docs/robot/autonomy/dds_router.md
          - airstack_msgs: common/ros_packages/msgs/airstack_msgs/README.md
      - Containers:
          - Robot: docs/robot/docker/index.md
          - Isaac Sim: docs/simulation/isaac_sim/docker.md
          - Microsoft AirSim (legacy): docs/simulation/ms-airsim/docker.md
          - Simple Sim: docs/simulation/simple_sim/docker.md
          - GCS: docs/gcs/docker/index.md
      - Deployment Topologies: docs/robot/autonomy_modes.md
      - Platform Matrix: docs/real_world/supported_platforms.md
      - Reference Stacks:
          - full_default: stacks/full_default/README.md
          - full_droan_cpu: stacks/full_droan_cpu/README.md
          - full_macvo: stacks/full_macvo/README.md
          - full_mighty: stacks/full_mighty/README.md
          - lite_default: stacks/lite_default/README.md
          - lite_offload_global: stacks/lite_offload_global/README.md
      - Modules Catalog:
          - Catalog: docs/modules/index.md
          - module.yaml Schema: common/module_schema/README.md
          - dfm2_disturbances: docs/modules/dfm2_disturbances.md
          - macvo: docs/modules/macvo.md
          - mighty: docs/modules/mighty.md
          - optitrack: docs/modules/optitrack.md
      - Autonomy Packages:
          - Robot Overview: docs/robot/index.md
          - Autonomy Overview: docs/robot/autonomy/index.md
          - Interface: docs/robot/autonomy/interface/index.md
          - Sensors:
              - Overview: docs/robot/autonomy/sensors/index.md
              - LiDAR Point Cloud Filter: robot/ros_ws/src/sensors/lidar_point_cloud_filter/README.md
          - Perception:
              - Overview: docs/robot/autonomy/perception/index.md
              - OptiTrack (asm_optitrack module): docs/robot/optitrack.md
          - Local:
              - Overview: docs/robot/autonomy/local/index.md
              - World Model: docs/robot/autonomy/local/world_model/index.md
              - Disparity Expansion: robot/ros_ws/src/local/world_models/disparity_expansion/README.md
              - Disparity Graph: robot/ros_ws/src/local/world_models/disparity_graph/README.md
              - Disparity Graph Cost Map: robot/ros_ws/src/local/world_models/disparity_graph_cost_map/README.md
              - Planning: docs/robot/autonomy/local/planning/index.md
              - Trajectory Library: robot/ros_ws/src/local/planners/trajectory_library/README.md
              - Takeoff Landing Planner: robot/ros_ws/src/local/planners/takeoff_landing_planner/README.md
              - Takeoff Landing Testing: robot/ros_ws/src/local/planners/takeoff_landing_planner/test/README.md
              - DROAN Local Planner: robot/ros_ws/src/local/planners/droan_local_planner/README.md
              - DROAN GL: robot/ros_ws/src/local/planners/droan_gl/README.md
              - Controls: docs/robot/autonomy/local/controls/index.md
              - Trajectory Controller: robot/ros_ws/src/local/controls/trajectory_controller/README.md
          - Global:
              - Overview: docs/robot/autonomy/global/index.md
              - World Model: docs/robot/autonomy/global/world_model/index.md
              - VDB Mapping: robot/ros_ws/src/global/world_models/vdb_mapping_ros2/README.md
              - Planning: docs/robot/autonomy/global/planning/index.md
              - Random Walk: robot/ros_ws/src/global/planners/random_walk/README.md
              - Exploration: robot/ros_ws/src/global/planners/exploration/README.md
          - Behavior: docs/robot/autonomy/behavior/index.md
          - Coordination: docs/robot/autonomy/coordination/index.md
          - RViz Tasks Panel: common/ros_packages/gui/rviz/rviz_tasks_panel/README.md
          - RViz 3D Waypoint Plugin: common/ros_packages/gui/rviz/3d_waypoint_rviz2_plugin/README.md
          - Bag Recorder: common/ros_packages/logging/bag_recorder_pid/README.md
      - CI & Testing:
          - System Test Suite: tests/README.md
          - CI/CD Orchestrator Runbook: tests/ci-cd-orchestrator.md
          - OSMO Lab Admin Guide: osmo/README.md
      - AI Agent Guide: docs/development/advanced/ai_agent_guide.md
  - Release Notes: docs/release_notes/index.md
  - About: docs/about.md
plugins:
  - search
  # the same-dir plugin lets mkdocs point to README.md files under our source code, not just the docs directory
  - same-dir
  # redirects is necessary with the same-dir plugin to ensure that the home page index.md file redirects to the correct location
  - redirects:
      redirect_maps:
        'index.md': 'docs/index.md'
        # Fossil pages removed in the Diátaxis docs overhaul
        'docs/simulation/isaac_sim/scene_setup.md': 'docs/simulation/isaac_sim/pegasus_scene_setup.md'
        'docs/simulation/isaac_sim/ascent_sitl_extension.md': 'docs/simulation/isaac_sim/pegasus_scene_setup.md'
        'docs/development/intermediate/testing/testing_frameworks.md': 'docs/development/intermediate/testing/index.md'
        'docs/development/development_environment.md': 'docs/development/beginner/development_environment.md'
        'docs/development/airstack-cli/index.md': 'docs/development/beginner/airstack-cli/index.md'
        'docs/tutorials/index.md': 'docs/getting_started/tutorials_reference.md'
repo_name: castacks/AirStack
repo_url: https://github.com/castacks/AirStack
# Per-page "Edit this page" pencil (theme feature content.action.edit).
# docs_dir is the repo root, so page paths are already repo-relative.
# GitHub shows contributors without write access its fork-and-edit flow.
# The develop docs deploy overrides the branch via DOCS_EDIT_URI.
edit_uri: !ENV [DOCS_EDIT_URI, "edit/main/"]
theme:
  favicon: docs/assets/StackedWhite.png
  custom_dir: docs/overrides
  features:
    - navigation.indexes
    - navigation.path
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.instant
    - navigation.instant.progress
    - navigation.tracking
    # - navigation.expand
    - navigation.footer
    - navigation.top
    - navigation.sections
    - search.highlight
    - search.suggest
    - search.share
    - toc.integrate
    - toc.follow
    - content.code.copy
    - content.code.annotate
    - content.tooltips
    - content.action.edit
  font:
    text: Inter
    code: JetBrains Mono
  logo: docs/assets/airstack_white.png
  name: material
  palette:
    - accent: custom
      primary: custom
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - accent: custom
      primary: custom
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode