mkdocs.yml

# $schema: https://squidfunk.github.io/mkdocs-material/schema.json

# --------------------------------------------------------------------------------------------------------------------#
# General information
# --------------------------------------------------------------------------------------------------------------------#

# Project information
site_name: "Sen"
site_description: "Sen Software Infrastructure"
# The published site, not the repository: this is what every page advertises as
# its canonical URL, and what sitemap.xml is built from.
site_url: https://airbus.github.io/sen/
site_author: "Airbus SAS, Airbus Helicopters, and Airbus Defence and Space SAU/GmbH/SAS"

# Screenshots and recordings are not in this branch. They live on the `docs-assets`
# branch of the same repository and are referenced by raw.githubusercontent URL, so the
# binaries stay out of the source history. Deleting that branch blanks images across six
# pages, and nothing in a build would fail. It is protected against deletion for that
# reason. Note GitHub serves .mp4 as application/octet-stream, so animated media there
# has to be GIF or WebP, not video.

# Repository
repo_name: airbus/sen
repo_url: https://github.com/airbus/sen.git

# A broken link is a build failure, not a line in a log nobody reads. MkDocs 1.6
# has no error level for these, so warn plus strict is the strongest available.
strict: true
validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

# Copied into the site from examples/ so their pages resolve, but they belong to
# the gallery rather than the navigation.
not_in_nav: |
  snippets/*
  includes/*

# Copyright
copyright: &copy Airbus SAS, Airbus Helicopters, and Airbus Defence and Space SAU/GmbH/SAS.

# --------------------------------------------------------------------------------------------------------------------#
# Theme
# --------------------------------------------------------------------------------------------------------------------#
theme:
  name: material
  logo: assets/images/logo_simple.svg
  favicon: assets/images/logo_simple.svg
  font: false
  palette:
    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/weather-night
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.tracking
    - navigation.footer
    - navigation.top
    - content.code.annotate
    - content.code.copy
    - content.tooltips
    - toc.follow
    - toc.integrate
  icon:
    repo: fontawesome/brands/github
    admonition:
      note: octicons/note-16

# --------------------------------------------------------------------------------------------------------------------#
# Extra
# --------------------------------------------------------------------------------------------------------------------#
extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.js

extra_css:
  - stylesheets/extra.css

extra:
  version:
    provider: mike
  generator: false

# --------------------------------------------------------------------------------------------------------------------#
# Markdown
# --------------------------------------------------------------------------------------------------------------------#
markdown_extensions:
  - toc:
      permalink: true
      toc_depth: 10
  # util_library.md writes formulas as $...$ and $$...$$. MathJax 3 renders
  # display maths on its own but leaves single-dollar inline maths alone, so
  # without this the inline formulas reached the reader as literal text.
  - pymdownx.arithmatex:
      generic: true
  - admonition
  - def_list
  # Acronym tooltips. 26 of the 30 acronyms in the corpus were expanded nowhere at
  # all, and the front page opens its feature list with five of them in two lines.
  # The definitions live in one file, appended to every page below, so a hover
  # resolves the word where the reader meets it rather than sending them away.
  - abbr
  - pymdownx.tasklist
  - pymdownx.details
  - pymdownx.critic
  - tables
  - footnotes
  - md_in_html
  - pymdownx.inlinehilite
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.snippets:
      # docs/ first, then the repository root, so a page can include a marked
      # region of real compiled source rather than a copy of it that drifts.
      base_path:
        - docs
        - .
      # A snippet whose file has moved is a build failure, not an empty block.
      check_paths: true
      # Appended to every page so the `abbr` definitions above apply site-wide.
      # One file to maintain, and no page has to remember to include it.
      auto_append:
        - includes/abbreviations.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.keys
  - pymdownx.details
  - attr_list
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

plugins:
  # Without a separator that splits on ':' and '<', a name like
  # sen::StaticVector<T, size> is indexed as one token and cannot be searched for.
  - search:
      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - callouts
  - offline
  # Every image becomes a lightbox, which is on for the FOM diagram: it is the one picture
  # nobody can read at page width. `manual` is off, so per-image `.on-glb` marks do nothing.
  - glightbox
  - git-revision-date-localized:
      enable_creation_date: false
      fallback_to_build_date: true
      # Generated at build time and never committed, so the plugin finds no
      # history and warns once per file: 38 warnings, which strict mode would
      # turn into a failed build.
      exclude:
        - snippets/*
        - licenses/licensed_code_in_sen.md
  - redoc-tag:
      height: 100vh

# --------------------------------------------------------------------------------------------------------------------#
# Navigation
# --------------------------------------------------------------------------------------------------------------------#
nav:
  - Home: index.md
  - Getting Started:
      - getting_started/index.md
      - Getting Sen: getting_started/install.md
      - Tutorials:
          - tutorials/index.md
          - "Tutorial 1: Hello Sen": tutorials/hello_sen.md
          - "Tutorial 2: Two objects talking": tutorials/two_objects.md
          - "Tutorial 3: Two processes talking": tutorials/two_processes.md
      - Creating your first package: getting_started/first_package.md
  - Manual:
      - users_guide/index.md
      - Concepts: users_guide/main_concepts.md
      - Mental model: users_guide/mental_model.md
      - Workflow: users_guide/workflow.md
      - Execution model: users_guide/execution_model.md
      - Threading and object lifetime: users_guide/threading.md
      - The Sen Type Language:
          - Description: users_guide/stl.md
          - STL grammar: users_guide/stl_grammar.md
      - The Sen Query Language: users_guide/sql.md
      - Using HLA FOMs: users_guide/hla.md
      - Code generation: users_guide/code_generation.md
      - The configuration file: users_guide/configuration.md
      - Command line tools: users_guide/command_line.md
      - CMake integration: users_guide/cmake.md
      - Run-time compatibility: users_guide/compatibility_conversions.md
      - Versioning and compatibility: users_guide/versioning.md
      - The Sen libraries:
          - sen::core: users_guide/core_library.md
          - sen::db: users_guide/db_library.md
          - sen::db Python bindings: users_guide/db_python_bindings.md
          - sen::gen: users_guide/gen_library.md
          - sen::kernel: users_guide/kernel_library.md
          - sen::util: users_guide/util_library.md
      - FAQ: users_guide/faq.md
      - Glossary: users_guide/glossary.md
  - Components:
      - components/index.md
      - Explorer: components/explorer.md
      - Web explorer: components/webexplorer.md
      - Shell: components/shell.md
      - Influx: components/influx.md
      - Python: components/py.md
      - Recorder: components/recording.md
      - Replayer: components/replaying.md
      - Ether: components/ether.md
      - Log master: components/logmaster.md
      - REST: components/rest.md
      - JSON-RPC: components/jsonrpc.md
      - JSON-RPC TypeScript client: components/jsonrpc_ts_client.md
      - MCP Gateway: components/mcp_gateway.md
      - Tracy: components/tracy.md
  - Guides:
      - howto_guides/index.md
      - Working with objects: howto_guides/objects.md
      - The generated C++ code: howto_guides/generated_code.md
      - Using logs: howto_guides/logging.md
      - Using component groups: howto_guides/using_groups.md
      - Controlling the clock: howto_guides/controlling_clock.md
      - Python as config: howto_guides/python_config.md
      - Configuring component sleeping between updates: howto_guides/precision_sleeper_config.md
      - Using the Dead Reckoning library: howto_guides/dead_reckoning.md
      - Implementing unit tests: howto_guides/unit_tests.md
      - Integration testing: howto_guides/integration_tests.md
      - Writing a component (advanced): howto_guides/components.md
      - Connecting existing systems: howto_guides/connecting_existing_systems.md
      - Design considerations: howto_guides/considerations.md
      - Configuring your environment: howto_guides/configure_environment.md
      - Sharing interfaces between projects:
          - Creating Conan packages for Sen-based projects: howto_guides/creating_conan_packages.md
          - Generate exportable interfaces (STL files): howto_guides/exportable_interfaces.md
          - Use interfaces from imported packages: howto_guides/consuming_interfaces.md
          - Generate and consume specific CMake packages for interfaces: howto_guides/generate_interface_packages.md
      - Troubleshooting: howto_guides/troubleshooting.md
      - Networking with WSL2 and virtual machines: howto_guides/networking_wsl2_virtual_machines.md
      - Working on Sen itself:
          - Building Sen from source: howto_guides/building_from_source.md
          - Running Sen's own tests: getting_started/testing.md
  - Examples:
      - examples/index.md
      - Counter: snippets/examples/config/0_counter/readme.md
      - Simple package: snippets/examples/config/1_calculators/readme.md
      - Inheritance: snippets/examples/config/2_inheritance/readme.md
      - Updates: snippets/examples/config/3_aircraft/readme.md
      - Interests: snippets/examples/config/11_shapes/readme.md
      - Deferred methods: snippets/examples/config/12_fibonacci/readme.md
      - Checked properties: snippets/examples/config/13_timer/readme.md
      - Distributing work: snippets/examples/config/4_school/readme.md
      - Influx and Grafana: snippets/examples/config/8_influx/readme.md
      - Recorder: snippets/examples/config/6_recorder/readme.md
      - Replayer: snippets/examples/config/7_replayer/readme.md
      - Using Python: snippets/examples/config/10_python/readme.md
      - Request/response servers: snippets/examples/config/9_hla_servers/readme.md
      - JSON-RPC: snippets/examples/config/14_jsonrpc/readme.md
      - HTML reference: examples/generated_reference.md
      - Typeset reference (PDF): examples/generated_document.md
      - UML generation: examples/generated_uml.md
  - License:
      - licenses/index.md
      - External libraries: licenses/licensed_code_in_sen.md