mkdocs.yml

site_name: osrlib
site_url: https://mmacy.github.io/osrlib-python/
site_description: >-
  B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers,
  built on the Old-School Essentials SRD.
repo_url: https://github.com/mmacy/osrlib-python
repo_name: mmacy/osrlib-python

theme:
  name: material
  palette:
    # Light/dark toggle: the button flips between the two schemes and the site
    # remembers the reader's choice.
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

markdown_extensions:
  # Explicit heading ids ({ #anchor }) — the generated reference pages carry them so
  # docstrings can cross-reference the content-id indexes via autorefs.
  - attr_list
  # Syntax highlighting for fenced and inline code. highlight tokenizes with
  # Pygments; superfences enables the ```lang fences (and keeps them working
  # alongside the snippet markers); inlinehilite colors `#!lang ...` inline code.
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  # The front-end walk-throughs excerpt the real example sources via named snippet
  # sections (--8<-- markers), so the pages cannot drift from the code they teach;
  # check_paths fails the build when a marker disappears.
  - pymdownx.snippets:
      base_path: [.]
      check_paths: true
      # Sections excerpted from inside functions render at the page margin, not at
      # their source indentation.
      dedent_subsections: true

# The design documents live in docs/ beside the site pages but are not part of the
# published site; the adaptations register (adaptations.md) is a site page and stays.
exclude_docs: |
  spec.md
  phase-*-plan.md
  docstring-audit.md

strict: true

# `mkdocs serve` watches docs/ and mkdocs.yml by default, not the package source.
# The API reference is generated from src/ docstrings via mkdocstrings, so watch it
# too — otherwise docstring edits don't live-reload and the preview goes stale.
watch:
  - src

validation:
  nav:
    omitted_files: warn
    not_found: warn
    absolute_links: warn
  links:
    not_found: warn
    absolute_links: warn
    unrecognized_links: warn
    anchors: warn

nav:
  - Home: index.md
  - Getting started:
      - Quickstart: getting-started/quickstart.md
      - Building an adventure: getting-started/building-an-adventure.md
  - Guides:
      - Sessions, commands, and events: guides/sessions-commands-events.md
      - Views and visibility: guides/views-and-visibility.md
      - Determinism, saves, and replay: guides/determinism-saves-replay.md
      - Using the rules without a session: guides/rules-without-a-session.md
      - Listeners and flags: guides/listeners-and-flags.md
      - Gates, triggers, and quests: guides/gates-triggers-quests.md
      - Authoring custom classes, spells, monsters, and items: guides/authoring-custom-content.md
      - Ruleset options: guides/ruleset-options.md
  - Front ends:
      - The TUI crawler: front-ends/tui-crawler.md
      - The FastAPI pattern: front-ends/fastapi-pattern.md
      - LLM referees: front-ends/llm-referees.md
  - Reference:
      - API: reference/api/
      - Commands: reference/commands/
      - Events: reference/events/
      - Rejection codes: reference/rejection-codes.md
      - Message codes: reference/message-codes.md
      - RNG streams: reference/rng-streams.md
      - Content ids: reference/content-ids/
      - Adaptations register: adaptations.md
  - Licensing: licensing.md

plugins:
  - search
  # Explicit, so heading anchors register as cross-reference targets (the
  # auto-enabled instance skips the heading scan).
  - autorefs
  - gen-files:
      scripts:
        - tools/docs/gen_api_reference.py
        - tools/docs/gen_schema_reference.py
        - tools/docs/gen_rejection_codes.py
        - tools/docs/gen_message_codes.py
        - tools/docs/gen_content_ids.py
        - tools/docs/gen_licensing.py
  - literate-nav
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          # Remote inventories: resolve cross-references to external symbols against the
          # upstream docs instead of leaving them as plain text. pydantic covers the
          # BaseModel/Field surface the command, event, and game-state models expose;
          # python covers stdlib types in signatures and docstrings (e.g. Enum, Path).
          inventories:
            - https://docs.pydantic.dev/latest/objects.inv
            - https://docs.python.org/3/objects.inv
          options:
            docstring_style: google
            # Render the model fields, not only methods: for the frozen pydantic
            # models (commands, events, game state) the typed fields are the API
            # surface a front-end author reads. Hide the pydantic machinery
            # (model_config, the subclass hooks) and every underscore-prefixed name.
            show_if_no_docstring: true
            filters:
              - "!^_"
              - "!^model_config$"
              - "!^model_fields$"
              - "!^model_computed_fields$"
            show_root_heading: false
            show_source: false
            members_order: source
            separate_signature: true
            show_signature_annotations: true
            signature_crossrefs: true
            line_length: 120
            merge_init_into_class: true