mkdocs.yml

# =========================================================================
# ResDAG documentation — "laboratory notebook, set in type"
# =========================================================================
# Journey-based structure: Start (productive in 10 min) → Build (the
# composition handbook) → Work (train/forecast/tune/deploy) → Theory (the
# math) → Reference (auto-generated) → Project.
#
# Design system lives in docs/css/notebook.css; the bespoke landing page
# template in docs/overrides/home.html.
#
# Local preview:    mkdocs serve
# Production build: mkdocs build --strict
# =========================================================================

site_name: ResDAG
site_description: >-
  Reservoir computing for PyTorch — composable Echo State Networks and
  next-generation reservoir computers, trained in one pass, on the GPU.
site_url: https://el3ssar.github.io/ResDAG/
site_author: Daniel Estevez-Moya

repo_name: El3ssar/ResDAG
repo_url: https://github.com/El3ssar/ResDAG
edit_uri: edit/main/docs/
copyright: >-
  Copyright © 2024–2026 Daniel Estevez-Moya — MIT License

docs_dir: docs

exclude_docs: |
  _tooling/

hooks:
  - hooks/docs_autogen.py

theme:
  name: material
  custom_dir: docs/overrides
  language: en
  favicon: assets/favicon.svg
  logo: assets/logo.svg
  icon:
    repo: fontawesome/brands/github
  font:
    text: Figtree
    code: IBM Plex Mono
  palette:
    # Paper-first: light is the primary reading surface.
    - scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Switch to dark
    - scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to light
  features:
    - content.code.annotate
    - content.code.copy
    - content.tabs.link
    - navigation.footer
    - navigation.indexes
    - navigation.instant
    - navigation.instant.progress
    - navigation.tabs
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.suggest
    - toc.follow

extra:
  generator: false
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/El3ssar/ResDAG
      name: ResDAG on GitHub
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/resdag/
      name: ResDAG on PyPI

extra_css:
  - css/notebook.css
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css

extra_javascript:
  - js/math.js
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - glightbox:
      effect: zoom
      zoomable: true
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src]
          inventories:
            - https://docs.python.org/3/objects.inv
            - https://pytorch.org/docs/stable/objects.inv
            - https://numpy.org/doc/stable/objects.inv
            - https://networkx.org/documentation/stable/objects.inv
          options:
            docstring_style: numpy
            docstring_section_style: spacy
            docstring_options:
              ignore_init_summary: true
            show_root_heading: true
            show_root_full_path: false
            show_object_full_path: false
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            show_signature_annotations: true
            signature_crossrefs: true
            separate_signature: true
            line_length: 88
            merge_init_into_class: true
            show_source: true
            show_bases: true
            inherited_members: false
            members_order: source
            heading_level: 2
            filters:
              - "!^_"
              - "^__init__$"

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      title: On this page
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: El3ssar
      repo: resdag
  - pymdownx.snippets:
      check_paths: true
      base_path: [., docs, examples]
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true

nav:
  - Home: index.md
  - Start:
      - start/index.md
      - Install: start/install.md
      - First forecast: start/first-forecast.md
      - The mental model: start/concepts.md
  - Build:
      - build/index.md
      - Layers:
          - build/layers/index.md
      - Readouts:
          - build/readouts/index.md
      - Architectures:
          - build/architectures/index.md
      - Initialization:
          - build/initialization/index.md
          - Topologies:
              - build/initialization/topologies/index.md
          - Initializers:
              - build/initialization/initializers/index.md
  - Work:
      - workflows/index.md
      - Train: workflows/train.md
      - Forecast: workflows/forecast.md
      - Lyapunov time: workflows/lyapunov.md
      - NG-RC: workflows/ngrc.md
      - Tune: workflows/tune.md
      - Streaming & DataLoaders: workflows/streaming.md
      - Scale & deploy: workflows/deploy.md
      - Benchmarks: workflows/benchmarks.md
  - Migrating: migrating.md
  - Theory:
      - theory/index.md
      - Reservoir dynamics: theory/dynamics.md
      - Readout solvers: theory/readout.md
      - Timing conventions: theory/timing.md
      - Design of the library: theory/design.md
  - Reference:
      - reference/index.md
      - Top level: reference/top-level.md
      - Facade: reference/facade.md
      - Core: reference/core.md
      - Layers: reference/layers.md
      - Initialization: reference/init.md
      - Training: reference/training.md
      - Metrics: reference/metrics.md
      - Models & ensembles: reference/models.md
      - HPO: reference/hpo.md
      - Utilities: reference/utils.md
  - Project:
      - project/index.md
      - Citation: project/citation.md
      - Ecosystem: project/ecosystem.md
      - Related work: project/related-work.md
      - Contributing: project/contributing.md
      - Changelog: project/changelog.md

validation:
  omitted_files: warn
  absolute_links: warn