mkdocs.yml

# Project information
site_name: langevin
site_url: https://cstarkjp.github.io/langevin/
site_author: Colin P. Stark
site_description: >-
  Tools to integrate Langevin equations of absorbing phase transition (APT)
  type — with a focus on simulation of directed percolation (DP).
  

# Repository
repo_name: cstarkjp/langevin
repo_url: https://github.com/cstarkjp/langevin

# https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/?h=edit+uri#code-actions
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright © 2025 Colin P. Stark

# mkdocs,
# readthedocs, material, cerulean, cosmo, cyborg,
# darkly, flatly, journal, litera, lumen, lux, materia, minty,
# pulse, sandstone, simplex, slate, solar, spacelab, 
# superhero, united, yeti
theme:
  # name: "readthedocs"
  name: "material"
  # custom_dir: docs/material-overrides
  # name: "materia"
  # name: "sandstone"
  # name: "spacelab"
  # name: "yeti"
  favicon: images/DP1.png
  logo: assets/DP5.png
  features:
    # - navigation.tabs
    # - content.action.edit
    - content.action.view
    - content.code.annotate
    - content.code.copy
    - content.code.select
    - content.footnote.tooltips
    - content.tabs.link
    - content.tooltips
    # - header.autohide
    # - navigation.expand
    - navigation.footer
    - navigation.indexes
    # - navigation.instant
    # - navigation.instant.prefetch
    # - navigation.instant.progress
    # - navigation.prune
    - navigation.sections
    - navigation.tabs
    # - navigation.tabs.sticky
    # - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow

  # font:
  #   text: Roboto
  #   code: Roboto Mono

  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/link
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/toggle-switch-off
        name: Switch to system preference
        
# Additional configuration
extra:
  status:
    new: Recently added
    deprecated: Deprecated
  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/cstarkjp/langevin
    # - icon: fontawesome/brands/docker
    #   link: https://hub.docker.com/r/squidfunk/mkdocs-material/
    # - icon: fontawesome/brands/python
    #   link: https://pypi.org/project/mkdocs-material/
    # - icon: fontawesome/brands/bluesky
    #   link: https://bsky.app/profile/squidfunk.bsky.social
    # - icon: fontawesome/brands/mastodon
    #   link: https://fosstodon.org/@squidfunk
    # - icon: fontawesome/brands/x-twitter
    #   link: https://x.com/squidfunk

# not_in_nav: |
#   /tutorials/**/*.md

nav:
    - Home: index.md
    - Navigation: navigation.md
    - Software design: software-design.md
    - How to install: how-to-install.md
    - Demos: demos-reference.md
    - How to run: how-to-run.md
    - Simulation tools: 
      - simulation-tools/index.md
      - Notebooks:
          - dp/DPSimulationDirect.ipynb: simulation-tools/dp-DPSimulationDirect-ipynb-reference.md
          - dp/DPSimulation.ipynb: simulation-tools/dp-DPSimulation-ipynb-reference.md
          - dp/DPEnsemble.ipynb: simulation-tools/dp-DPEnsembleSimulation-ipynb-reference.md
      - Scripts:
          - dp/dp_simulation.py: simulation-tools/dp-simulation-py-reference.md
          - dp/dp_ensemble_simulation.py: simulation-tools/dp-ensemble_simulation-py-reference.md
          - dp/dp_batch_ensemble.py: simulation-tools/dp-batch_ensemble-py-reference.md
      - JSON info files: 
          - Example: simulation-tools/info-reference.md
    - Python modules: 
        - python-modules/index.md
        - base:
          - base/file.py: python-modules/file-reference.md 
          - base/serialize.py: python-modules/serialize-reference.md 
          - base/utils.py: python-modules/utils-reference.md 
          - base/viz.py: python-modules/viz-reference.md
        - dp:
          - dp/ensemble.py: python-modules/ensemble-reference.md
          - dp/simulation.py: python-modules/simulation-reference.md
          - dp/vizdp.py: python-modules/vizdp-reference.md
    - C++ source: 
      - cplusplus-source/index.md
      # - cplusplus-source/cplusplus.md
    - References: references.md

# https://analog-garage.github.io/mkdocstrings-python-xref/latest/
# https://github.com/mkdocstrings/autorefs
# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#arithmatex

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.blocks.admonition
  - pymdownx.blocks.details
  - pymdownx.blocks.caption
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.extra
  - pymdownx.fancylists
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: cstarkjp
      repo: langevin
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      auto_append:
        - includes/mkdocs.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde



extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js # Example using a CDN
  - javascripts/extra.js

extra_css:
  - style.css

plugins:
- search
- autorefs  
- caption
- mkdocstrings:
    handlers:
      python:

        # Where to find your sources, see "Finding modules".
        paths: [python, demos]
        # paths_recursive: true

        # Load object inventories to enable cross-references to other projects.
        inventories:
        - https://docs.python.org/3/objects.inv
        # Also load inventories of your dependencies, generally served at
        # https://docs-url-for-your-dependency/objects.inv.

        options:
          docstring_style: google

          # DOCSTRINGS -------------------------------------------------------------
          docstring_options:
            # Discard first line of `__init__` method docstrings,
            # useful when merging such docstrings into their parent class'.
            ignore_init_summary: true

          # Tables are generally too large, lists will fix this.
          docstring_section_style: list

          # CROSS-REFERENCES -------------------------------------------------------
          # Enable relative crossrefs and scoped crossrefs, see Docstrings options.
          relative_crossrefs: true  # Sponsors only!
          scoped_crossrefs: true  # Sponsors only!

          # Enable cross-references in signatures.
          signature_crossrefs: true

          # Unwrap actual types from `Annotated` type annotations.
          unwrap_annotated: true


          # MEMBERS ----------------------------------------------------------------
          # Only render pulic symbols.
          filters: public  # Sponsors only!
          # Comment the option otherwise to get the default filters.

          # Show class inherited members.
          inherited_members: true

          # Render auto-generated summaries of attributes, functions, etc.
          # at the start of each symbol's documentation.
          summary: true

          # HEADINGS ---------------------------------------------------------------
          # For auto-generated pages, one module per page,
          # make the module heading be the H1 heading of the page.
          heading_level: 1

          # Render headings for parameters, making them linkable.
          parameter_headings: true

          # Render headings for type parameters too.
          type_parameter_headings: true

          # Always show the heading for the symbol you render with `::: id`.
          show_root_heading: true

          # Only show the name of the symbols you inject render `::: id`.
          show_root_full_path: false

          # Show the type of symbol (class, function, etc.) in the heading.
          show_symbol_type_heading: true

          # Show the type of symbol (class, function, etc.) in the table of contents.
          show_symbol_type_toc: true

          # SIGNATURES -------------------------------------------------------------
          # Format code to 80 + 10% margin (Black and Ruff defaults)
          # in signatures and attribute value code blocks.
          # Needs Black/Ruff installed.
          line_length: 88

          # Merge signature and docstring of `__init__` methods
          # into their parent class signature and docstring.
          merge_init_into_class: true

          # Render signatures and attribute values in a separate code block,
          # below the symbol heading.
          separate_signature: true

          # Show type annotations in signatures.
          show_signature_annotations: true

          # Show type parameters in signatures.
          show_signature_type_parameters: true

          # OTHER ------------------------------------------------------------------
          # Show backlinks to other documentation sections within each symbol.
          backlinks: tree  # Sponsors only!

          # Show base classes OR inheritance diagram.
          show_bases: false
          show_inheritance_diagram: true  # Sponsors only!

# - mkdoxy:
#     projects:
#       langevin: # name of project must be alphanumeric + numbers (without spaces)
#         src-dirs: cplusplus # path to source code (support multiple paths separated by space) => INPUT
#         full-doc: True # if you want to generate full documentation
#         # doxy-cfg-file: Doxyfile 
#         doxy-cfg: # standard doxygen configuration (key: value)
#           FILE_PATTERNS: "*.cpp *.h*" # specify file patterns to filter out
#           RECURSIVE: True # recursive search in source directories
#           DOXYFILE_ENCODING: UTF-8
#           PROJECT_NUMBER:
#           PROJECT_BRIEF:
#           PROJECT_LOGO:
#           PROJECT_ICON:
#           OUTPUT_DIRECTORY:
#           CREATE_SUBDIRS: NO
#           CREATE_SUBDIRS_LEVEL: 8
#           ALLOW_UNICODE_NAMES: NO
#           OUTPUT_LANGUAGE: English
#           BRIEF_MEMBER_DESC: YES
#           REPEAT_BRIEF: YES