mkdocs.yml

# FlixOpt Documentation Configuration
# https://mkdocstrings.github.io/python/usage/configuration/docstrings/
# https://squidfunk.github.io/mkdocs-material/setup/

site_name: flixopt
site_description: Energy and Material Flow Optimization Framework
site_url: https://flixopt.github.io/flixopt/
repo_url: https://github.com/flixOpt/flixopt
repo_name: flixOpt/flixopt
edit_uri: edit/main/docs/

nav:
  - Home:
    - Home: index.md
    - Getting Started:
      - Installation: home/installation.md
      - Quick Start: home/quick-start.md
    - About:
      - Users: home/users.md
      - Citing: home/citing.md
      - License: home/license.md

  - User Guide:
    - Overview: user-guide/index.md
    - Core Concepts: user-guide/core-concepts.md
    - Glossary: user-guide/glossary.md
    - Building Models:
      - Overview: user-guide/building-models/index.md
      - Choosing Components: user-guide/building-models/choosing-components.md
    - Running Optimizations: user-guide/optimization/index.md
    - Analyzing Results: user-guide/results/index.md
    - Plotting:
      - Plotting Results: user-guide/results-plotting.md
      - Color Management: user-guide/colors.md
      - Plotly Customization: user-guide/plotly-customization.md
    - Mathematical Notation:
      - Overview: user-guide/mathematical-notation/index.md
      - Bus: user-guide/mathematical-notation/elements/Bus.md
      - Flow: user-guide/mathematical-notation/elements/Flow.md
      - LinearConverter: user-guide/mathematical-notation/elements/LinearConverter.md
      - Storage: user-guide/mathematical-notation/elements/Storage.md
      - Effects & Dimensions: user-guide/mathematical-notation/effects-and-dimensions.md
      - Investment: user-guide/mathematical-notation/features/InvestParameters.md
      - Status: user-guide/mathematical-notation/features/StatusParameters.md
      - Piecewise: user-guide/mathematical-notation/features/Piecewise.md
    - Recipes:
      - user-guide/recipes/index.md
      - Plotting Custom Data: user-guide/recipes/plotting-custom-data.md
    - Support:
      - FAQ: user-guide/faq.md
      - Troubleshooting: user-guide/troubleshooting.md
      - Community: user-guide/support.md
    - Migration & Updates:
      - Migration Guide v6: user-guide/migration-guide-v6.md
      - Migration Guide v5: user-guide/migration-guide-v5.md
      - Migration Guide v3: user-guide/migration-guide-v3.md
      - Release Notes: changelog.md
      - Roadmap: roadmap.md

  - Examples:
    - Overview: notebooks/index.md
    - Basics:
      - Quickstart: notebooks/01-quickstart.ipynb
      - Heat System: notebooks/02-heat-system.ipynb
    - Investment:
      - Sizing: notebooks/03-investment-optimization.ipynb
      - Constraints: notebooks/04-operational-constraints.ipynb
    - Advanced:
      - Multi-Carrier: notebooks/05-multi-carrier-system.ipynb
      - Transmission: notebooks/10-transmission.ipynb
    - Non-Linear Modeling:
      - Time-Varying Parameters: notebooks/06a-time-varying-parameters.ipynb
      - Piecewise Conversion: notebooks/06b-piecewise-conversion.ipynb
      - Piecewise Effects: notebooks/06c-piecewise-effects.ipynb
    - Scaling:
      - Scenarios: notebooks/07-scenarios-and-periods.ipynb
      - Aggregation: notebooks/08a-aggregation.ipynb
      - Rolling Horizon: notebooks/08b-rolling-horizon.ipynb
      - Clustering:
        - Introduction: notebooks/08c-clustering.ipynb
        - Storage Modes: notebooks/08c2-clustering-storage-modes.ipynb
        - Multi-Period: notebooks/08d-clustering-multiperiod.ipynb
        - Segmentation: notebooks/08f-clustering-segmentation.ipynb
        - Internals: notebooks/08e-clustering-internals.ipynb
    - Results:
      - Plotting: notebooks/09-plotting-and-data-access.ipynb

  - API Reference: api-reference/

  - Contributing: contribute.md

theme:
  name: material
  language: en
  custom_dir: docs/overrides

  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: teal
      accent: cyan
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: cyan
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

  font:
    text: Roboto  # Clean, technical documentation font
    code: Fira Code  # Beautiful code font with ligatures

  logo: images/flixopt-icon.svg
  favicon: images/flixopt-icon.svg

  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye
    annotation: material/plus-circle

  features:
    # Navigation
    - navigation.instant
    - navigation.instant.progress
    - navigation.instant.prefetch
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.path  # Show breadcrumb path
    - navigation.prune  # Only render visible navigation
    - navigation.indexes
    - navigation.top
    - navigation.footer

    # Table of contents
    - toc.follow

    # Search
    - search.suggest
    - search.highlight
    - search.share

    # Content
    - content.action.edit
    - content.action.view
    - content.code.copy
    - content.code.select
    - content.code.annotate
    - content.tooltips
    - content.tabs.link  # Link content tabs across pages

    # Header
    - announce.dismiss  # Allow dismissing announcements

markdown_extensions:
  # Content formatting
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      permalink_title: Anchor link to this section
      toc_depth: 3
      title: On this page

  # Code blocks
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
      auto_title: false
      use_pygments: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path: ..
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: plotly
          class: mkdocs-plotly
          format: !!python/name:mkdocs_plotly_plugin.fences.fence_plotly

  # Enhanced content
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
  - pymdownx.tasklist:
      custom_checkbox: true

  # Typography
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.smartsymbols
  - pymdownx.keys

  # Math
  - pymdownx.arithmatex:
      generic: true

  # Icons & emojis
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

  # Legacy support
  - markdown_include.include:
      base_path: docs

plugins:
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'

  - mkdocs-jupyter:
      execute: !ENV [MKDOCS_JUPYTER_EXECUTE, true]  # CI pre-executes in parallel
      allow_errors: false
      include_source: true
      include_requirejs: true
      ignore:
        - "notebooks/data/*.py"  # Data generation scripts, not notebooks
      execute_ignore:
        - "notebooks/data/*.py"

  - plotly

  - table-reader

  - include-markdown

  - mike:
      alias_type: symlink
      redirect_template: null
      deploy_prefix: ''
      canonical_version: null
      version_selector: true
      css_dir: css
      javascript_dir: js

  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: true

  - gen-files:
      scripts:
        - scripts/gen_ref_pages.py

  - mkdocstrings:
      enabled: !ENV [ENABLE_MKDOCSTRINGS, true]
      default_handler: python
      handlers:
        python:
          paths: [.]
          inventories:
            - https://docs.python.org/3/objects.inv
            - https://numpy.org/doc/stable/objects.inv
            - https://pandas.pydata.org/docs/objects.inv
          options:
            # Docstring parsing
            docstring_style: google
            docstring_section_style: table

            # Member ordering and filtering
            members_order: source
            inherited_members: false
            show_if_no_docstring: false
            filters: ["!^_", "^__init__$"]
            group_by_category: true

            # Headings and structure
            heading_level: 1
            show_root_heading: true
            show_root_toc_entry: false
            show_category_heading: true

            # Signatures
            show_signature: true
            show_signature_annotations: true
            separate_signature: true
            line_length: 80

            # Source and paths
            show_source: false
            show_object_full_path: false

            # Attributes and annotations
            show_docstring_attributes: true
            modernize_annotations: true
            merge_init_into_class: true

            # Improved type hints
            annotations_path: brief

  # Optional: Add git info
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
      fallback_to_build_date: true

  # Optional: Add better navigation
  - tags

  # Optional: Minify HTML in production
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

extra:
  version:
    provider: mike
    default: latest
    alias: true

  social:
    - icon: fontawesome/brands/github
      link: https://github.com/flixOpt/flixopt
      name: FlixOpt on GitHub
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/flixopt/
      name: FlixOpt on PyPI

  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: >-
            Thanks for your feedback! Help us improve by
            <a href="https://github.com/flixOpt/flixopt/issues/new" target="_blank" rel="noopener">opening an issue</a>.

  status:
    new: Recently added
    deprecated: Deprecated

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/mathjax.js
  - javascripts/plotly-instant.js
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6

watch:
  - flixopt
  - docs