mkdocs.yml

site_name: modern-di
site_url: https://modern-di.modern-python.org
repo_url: https://github.com/modern-python/modern-di
docs_dir: docs
edit_uri: edit/main/docs/
nav:
  - Quickstart: index.md
  - Introduction:
      - About DI: introduction/about-di.md
      - Resolving: introduction/resolving.md
      - Design decisions: introduction/design-decisions.md
      - Comparison: introduction/comparison.md
      - Performance: introduction/performance.md
  - Providers:
      - Scopes: providers/scopes.md
      - Lifecycle: providers/lifecycle.md
      - Factories: providers/factories.md
      - Context: providers/context.md
      - Container: providers/container.md
      - Alias: providers/alias.md
      - Errors and exceptions: providers/errors-and-exceptions.md
      - Advanced / low-level API: providers/advanced-api.md
  - Integrations:
      - Web:
          - aiohttp: integrations/aiohttp.md
          - FastAPI: integrations/fastapi.md
          - Flask: integrations/flask.md
          - Litestar: integrations/litestar.md
          - Starlette: integrations/starlette.md
      - Tasks & events:
          - arq: integrations/arq.md
          - Celery: integrations/celery.md
          - FastStream: integrations/faststream.md
          - taskiq: integrations/taskiq.md
      - Bots:
          - aiogram: integrations/aiogram.md
      - RPC:
          - FastMCP: integrations/fastmcp.md
          - gRPC: integrations/grpc.md
      - CLI:
          - Typer: integrations/typer.md
      - Testing:
          - pytest: integrations/pytest.md
      - Writing an integration: integrations/writing-integrations.md
  - Recipes:
      - Async SQLAlchemy: recipes/sqlalchemy.md
      - Async resources via lifespan: recipes/async-lifespan.md
      - FastAPI and FastStream sharing a container: recipes/shared-container.md
      - Multi-group organization: recipes/multi-group.md
      - Testing with overrides: recipes/testing-overrides.md
      - Request-scoped engine selection: recipes/request-scoped-engine.md
      - Good and bad practices: recipes/good-and-bad-practices.md
      - Pydantic AI agents: recipes/pydantic-ai.md
  - Troubleshooting:
      - Invalid child scope: troubleshooting/invalid-child-scope-error.md
      - Max scope reached: troubleshooting/max-scope-reached-error.md
      - Scope not initialized: troubleshooting/scope-not-initialized-error.md
      - Scope skipped: troubleshooting/scope-skipped-error.md
      - Invalid scope type: troubleshooting/invalid-scope-type-error.md
      - Container closed: troubleshooting/container-closed-error.md
      - Validation failed: troubleshooting/validation-failed-error.md
      - Provider not registered: troubleshooting/missing-provider.md
      - Alias source not registered: troubleshooting/alias-source-not-registered-error.md
      - Alias bound to its source: troubleshooting/alias-bound-to-source-error.md
      - Argument resolution error: troubleshooting/argument-resolution-error.md
      - Circular dependency: troubleshooting/circular-dependency.md
      - Creator call error: troubleshooting/creator-call-error.md
      - ContextProvider has no value: troubleshooting/context-not-set.md
      - Duplicate provider type: troubleshooting/duplicate-type-error.md
      - Child container registration: troubleshooting/child-container-registration-error.md
      - Group scope conflict: troubleshooting/group-scope-conflict-error.md
      - Provider scope frozen: troubleshooting/provider-scope-frozen-error.md
      - Unknown factory kwarg: troubleshooting/unknown-factory-kwarg-error.md
      - Unsupported creator parameter: troubleshooting/unsupported-creator-parameter-error.md
      - Async creator: troubleshooting/async-creator-error.md
      - Invalid scope dependency: troubleshooting/scope-chain.md
      - Scope enum mismatch: troubleshooting/scope-enum-mismatch-error.md
      - Finalizer error: troubleshooting/finalizer-error.md
      - Async finalizer in sync close: troubleshooting/async-finalizer-in-sync-close-error.md
      - Group instantiation error: troubleshooting/group-instantiation-error.md
  - Migration:
      - To 1.x: migration/to-1.x.md
      - To 2.x: migration/to-2.x.md
      - To 3.x: migration/to-3.x.md
      - To 4.x: migration/to-4.x.md
      - From that-depends: migration/from-that-depends.md
      - From dependency-injector: migration/from-dependency-injector.md
  - Development:
      - Contributing: dev/contributing.md
      - Performance history: dev/performance-history.md

theme:
  name: material
  custom_dir: overrides
  logo: assets/mark.svg
  favicon: assets/favicon.svg
  features:
    - content.code.copy
    - content.code.annotate
    - content.action.edit
    - content.action.view
    - navigation.footer
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.instant
    - header.autohide
    - announce.dismiss
  icon:
    edit: material/pencil
    view: material/eye
    repo: fontawesome/brands/git-alt
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

# docs/agents/ is agent configuration, not user documentation; docs/adr/ records
# internal design decisions. Neither is published.
exclude_docs: |
  /agents/
  /adr/

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

markdown_extensions:
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - admonition
  - pymdownx.details
  - def_list
  - codehilite:
      use_pygments: true
  - attr_list
  - md_in_html

extra_css:
  - css/code.css
  - css/brand.css

plugins:
  - search
  - llmstxt:
      full_output: llms-full.txt
      markdown_description: "Powerful dependency-injection framework with IoC container and scopes."
      sections:
        Quickstart:
          - index.md: How to install and a minimal container example
        Introduction:
          - introduction/about-di.md: What dependency injection is and the problem it solves
          - introduction/resolving.md: Resolving dependencies by type or by provider reference
          - introduction/design-decisions.md: The deliberate API choices behind modern-di
          - introduction/comparison.md: How modern-di compares to other DI approaches, including that-depends
          - introduction/performance.md: Comparative benchmarks vs other DI frameworks, and how to reproduce them
        Providers:
          - providers/scopes.md: The five built-in scopes and the resolution rule
          - providers/lifecycle.md: How instances are created, cached, and cleaned up
          - providers/factories.md: Regular vs cached Factory providers
          - providers/context.md: Injecting runtime context values with ContextProvider
          - providers/container.md: "The Container API: building containers, a map of its methods, injecting the container itself, and registering or looking up providers"
          - providers/alias.md: Binding one type to an already-registered provider
          - providers/errors-and-exceptions.md: The ModernDIError exception hierarchy
          - providers/advanced-api.md: Low-level extension points for library authors
        Integrations:
          # Bulk-include every integration page so a new one needs no edit here;
          # the two lines below re-list the pages whose description adds info
          # beyond the nav label (a glob yields an empty description).
          - integrations/*.md
          - integrations/pytest.md: Usage with pytest, with and without modern-di-pytest
          - integrations/writing-integrations.md: Specification for building a new framework integration
        Recipes:
          - recipes/sqlalchemy.md: Wiring an async SQLAlchemy engine, session, and repositories
          - recipes/async-lifespan.md: Constructing async resources via the framework lifespan
          - recipes/shared-container.md: One container shared by a FastAPI app and a FastStream app in one process, with manage_lifespan=False
          - recipes/multi-group.md: Organizing a large container with multiple Groups
          - recipes/testing-overrides.md: Swapping dependencies in tests with overrides
          - recipes/request-scoped-engine.md: Routing requests to different engines by scope
          - recipes/good-and-bad-practices.md: Common DI footguns and how modern-di catches them
          - recipes/pydantic-ai.md: Passing a container as Pydantic AI deps, with an optional per-tool-call scope
        Troubleshooting:
          - troubleshooting/invalid-child-scope-error.md: Diagnosing InvalidChildScopeError
          - troubleshooting/max-scope-reached-error.md: Diagnosing MaxScopeReachedError
          - troubleshooting/scope-not-initialized-error.md: Diagnosing ScopeNotInitializedError
          - troubleshooting/scope-skipped-error.md: Diagnosing ScopeSkippedError
          - troubleshooting/invalid-scope-type-error.md: Diagnosing InvalidScopeTypeError
          - troubleshooting/container-closed-error.md: Diagnosing ContainerClosedError
          - troubleshooting/validation-failed-error.md: Diagnosing ValidationFailedError
          - troubleshooting/missing-provider.md: Diagnosing ProviderNotRegisteredError
          - troubleshooting/alias-source-not-registered-error.md: Diagnosing AliasSourceNotRegisteredError
          - troubleshooting/alias-bound-to-source-error.md: Diagnosing AliasBoundToSourceError
          - troubleshooting/argument-resolution-error.md: Diagnosing ArgumentResolutionError
          - troubleshooting/circular-dependency.md: Diagnosing CircularDependencyError
          - troubleshooting/creator-call-error.md: Diagnosing CreatorCallError
          - troubleshooting/context-not-set.md: Diagnosing ContextValueNotSetError
          - troubleshooting/duplicate-type-error.md: Diagnosing DuplicateProviderTypeError
          - troubleshooting/child-container-registration-error.md: Diagnosing ChildContainerRegistrationError
          - troubleshooting/group-scope-conflict-error.md: Diagnosing GroupScopeConflictError
          - troubleshooting/provider-scope-frozen-error.md: Diagnosing ProviderScopeFrozenError
          - troubleshooting/unknown-factory-kwarg-error.md: Diagnosing UnknownFactoryKwargError
          - troubleshooting/unsupported-creator-parameter-error.md: Diagnosing UnsupportedCreatorParameterError
          - troubleshooting/async-creator-error.md: Diagnosing AsyncCreatorError
          - troubleshooting/scope-chain.md: Diagnosing InvalidScopeDependencyError
          - troubleshooting/scope-enum-mismatch-error.md: Diagnosing ScopeEnumMismatchError
          - troubleshooting/finalizer-error.md: Diagnosing FinalizerError
          - troubleshooting/async-finalizer-in-sync-close-error.md: Diagnosing AsyncFinalizerInSyncCloseError
          - troubleshooting/group-instantiation-error.md: Diagnosing GroupInstantiationError
        Migration:
          - migration/to-1.x.md: Migrating from modern-di 0.x to 1.x
          - migration/to-2.x.md: Migrating from modern-di 1.x to 2.x
          - migration/to-3.x.md: Migrating from modern-di 2.x to 3.x
          - migration/to-4.x.md: Migrating from modern-di 3.x to 4.x
          - migration/from-that-depends.md: Migrating an existing that-depends codebase to modern-di
          - migration/from-dependency-injector.md: Migrating an existing dependency-injector codebase to modern-di
        Development:
          - dev/contributing.md: Contributing guide for local setup and workflow
          - dev/performance-history.md: Each resolve-path optimization and its measured effect

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/modern-python/modern-di
      name: GitHub