Add mdformat to pre-commit config

.circleci/config.yml

@@ -108,4 +108,4 @@ workflows:
         - equal: ["html-noplot", << pipeline.parameters.GHA_Meta >>]
     jobs:
       - build-docs:
-          make_target: << pipeline.parameters.GHA_Meta >>
+          make_target: << pipeline.parameters.GHA_Meta >>

.github/TEST_FAIL_TEMPLATE.md

@@ -9,4 +9,4 @@ with commit: {{ sha }}
 
 Full run: https://github.com/{{ payload.repository.full_name }}/actions/runs/{{ env.RUN_ID }}
 
-(This post will be updated if another test fails, as long as this issue remains open.)
+(This post will be updated if another test fails, as long as this issue remains open.)

.github/missing_translations.md

@@ -11,4 +11,3 @@ You can also Update the cron script to update this issue with better information
 
 Note that this issue will be automatically updated if kept open, or a new one will be created when necessary, if no open
 issue is found and new `_.trans` call are missing.
-

.github/workflows/triggered_target_build.yml

@@ -86,7 +86,7 @@ jobs:
             core.setOutput('pr_ref', pr.data.head.ref);
             core.setOutput('pr_sha', pr.data.head.sha);
             core.setOutput('pr_number', context.issue.number);
-      
+
       - name: Set docs ref
         id: set-docs-ref
         run: |

.gitignore

@@ -164,4 +164,4 @@ docs/_static/images/*.mp4
 # pixi environments
 .pixi/*
 !.pixi/config.toml
-pixi.lock
+pixi.lock

.mdformat.toml

@@ -0,0 +1,3 @@
+exclude = [
+    "docs/naps/*.md",
+]

.pre-commit-config.yaml

@@ -30,5 +30,12 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi ]
 
+- repo: https://github.com/executablebooks/mdformat
+  rev: 0.7.22
+  hooks:
+    - id: mdformat
+      additional_dependencies: [mdformat-myst, mdformat-ruff]
+      files: (docs/.)
+
 default_language_version:
     python: python3.13

.ruff.toml

@@ -0,0 +1,71 @@
+fix = true
+
+exclude = [
+    "docs/conf.py",
+    "docs/_scripts/*.py",
+    "docs/naps/*.md",
+]
+
+[format]
+quote-style = "single"
+
+[lint]
+select = [
+    "E", "F", "W", #flake8
+    "UP", # pyupgrade
+    "I", # isort
+    "YTT", #flake8-2020
+    "TC", # flake8-type-checing
+    "BLE", # flake8-blind-exception
+    "B", # flake8-bugbear
+    "A", # flake8-builtins
+    "C4", # flake8-comprehensions
+    "ISC", # flake8-implicit-str-concat
+    "G", # flake8-logging-format
+    "PIE", # flake8-pie
+    "COM", # flake8-commas
+    "SIM", # flake8-simplify
+    "INP", # flake8-no-pep420
+    "PYI", # flake8-pyi
+    "Q", # flake8-quotes
+    "RSE", # flake8-raise
+    "RET", # flake8-return
+    "TID",  # flake8-tidy-imports # replace absolutify import
+    "TRY", # tryceratops
+    "ICN", # flake8-import-conventions
+    "RUF", # ruff specyfic rules
+    "NPY201", # checks compatibility with numpy version 2.0
+    "ASYNC", # flake8-async
+    "EXE", # flake8-executable
+    "FA", # flake8-future-annotations
+    "LOG", # flake8-logging
+    "SLOT", # flake8-slots
+    "PT", # flake8-pytest-style
+    "T20", # flake8-print
+]
+ignore = [
+    "E501", "TC001", "TC002", "TC003",
+    "A003", # flake8-builtins - we have class attributes violating these rule
+    "COM812", # flake8-commas - we don't like adding comma on single line of arguments
+    "COM819", # conflicts with ruff-format
+    "RET504", # not fixed yet https://github.com/charliermarsh/ruff/issues/2950
+    "TRY003", # require implement multiple exception class
+    "RUF005", # problem with numpy compatybility, see https://github.com/charliermarsh/ruff/issues/2142#issuecomment-1451038741
+    "B028", # need to be fixed
+    "PYI015", # it produces bad looking files (@jni opinion)
+    "W191", "Q000", "Q001", "Q002", "Q003", "ISC001", # https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "UP007", # temporary disable migrtion form Union[X, Y] to X | Y
+    "UP045", # temporary disable migrtion from Optional[X] to X | None
+    "TC006", # put types in quotes in typing.cast
+]
+
+[lint.flake8-builtins]
+builtins-allowed-modules = ["io", "types", "threading"]
+
+[lint.pyupgrade]
+keep-runtime-typing = true
+
+[lint.flake8-quotes]
+docstring-quotes = "double"
+inline-quotes = "single"
+multiline-quotes = "double"

docs/_scripts/README.md

@@ -5,6 +5,7 @@ This directory contains Python scripts that automate various aspects of the napa
 ## Overview
 
 The `_scripts` folder is a critical part of the napari documentation infrastructure, containing automation tools that:
+
 - Generate GUI screenshots automatically
 - Extract and document events from the codebase
 - Create preference documentation with dialog images
@@ -18,12 +19,14 @@ The `_scripts` folder is a critical part of the napari documentation infrastruct
 **Purpose**: Master orchestration script that coordinates all documentation generation tasks.
 
 **Usage**:
+
 ```bash
 python docs/_scripts/prep_docs.py
 python docs/_scripts/prep_docs.py --stubs  # Fast mode with stub content
 ```
 
 **Functionality**:
+
 - Clones and processes the npe2 repository for plugin documentation
 - Executes all other documentation generation scripts in sequence
 - Supports a `--stubs` mode for faster development builds
@@ -34,17 +37,20 @@ python docs/_scripts/prep_docs.py --stubs  # Fast mode with stub content
 **Purpose**: Automatically captures screenshots of napari GUI components for use in documentation.
 
 **Usage**:
+
 ```bash
 python docs/_scripts/autogenerate_gui_images.py
 ```
 
 **Generated Content**:
+
 - `docs/images/_autogenerated/widgets/` - Individual widget screenshots
 - `docs/images/_autogenerated/menus/` - Menu screenshots
 - `docs/images/_autogenerated/popups/` - Popup dialog screenshots
 - `docs/images/_autogenerated/regions/` - Combined component regions
 
 **Key Features**:
+
 - Opens napari with sample data (cells3d)
 - Captures widgets, menus, popups, and viewer regions
 - Applies consistent dark theme
@@ -55,17 +61,20 @@ python docs/_scripts/autogenerate_gui_images.py
 **Purpose**: Analyzes the napari codebase to generate comprehensive event documentation.
 
 **Usage**:
+
 ```bash
 python docs/_scripts/update_event_docs.py
 python docs/_scripts/update_event_docs.py --stubs
 ```
 
 **Generated Content**:
+
 - `docs/guides/_viewer_events.md` - Viewer model events
 - `docs/guides/_layerlist_events.md` - Layer list events
 - `docs/guides/_layer_events.md` - Layer-specific events
 
 **Key Features**:
+
 - Uses AST parsing to discover EmitterGroup definitions
 - Extracts documentation from docstrings
 - Creates formatted tables with event names, descriptions, access patterns, and types
@@ -76,16 +85,19 @@ python docs/_scripts/update_event_docs.py --stubs
 **Purpose**: Generates preference documentation with screenshots of preference dialogs.
 
 **Usage**:
+
 ```bash
 python docs/_scripts/update_preference_docs.py
 python docs/_scripts/update_preference_docs.py --stubs
 ```
 
 **Generated Content**:
+
 - `docs/guides/preferences.md` - Complete preferences documentation
 - `docs/images/_autogenerated/preferences/` - Preference dialog screenshots
 
 **Key Features**:
+
 - Documents all settings from NapariSettings
 - Captures screenshots of each preference section
 - Uses Jinja2 templates for consistent formatting
@@ -96,12 +108,14 @@ python docs/_scripts/update_preference_docs.py --stubs
 **Purpose**: Generates architecture documentation for napari's UI components with dependency analysis.
 
 **Usage**:
+
 ```bash
 python docs/_scripts/update_ui_sections_docs.py
 python docs/_scripts/update_ui_sections_docs.py --stubs
 ```
 
 **Generated Content**:
+
 - `docs/developers/architecture/ui_sections/` - Architecture documentation for each UI section
   - `layers_list_ui.md`
   - `layers_controls_ui.md`
@@ -112,16 +126,18 @@ python docs/_scripts/update_ui_sections_docs.py --stubs
   - `console_ui.md`
 
 **Key Features**:
+
 - Uses pydeps for dependency analysis
 - Generates interactive Mermaid diagrams
 - Creates directory layout views
 - Links to source code on GitHub
 
-### _table_maker.py
+### `_table_maker.py`
 
 **Purpose**: Utility module for creating formatted ASCII/Markdown tables.
 
 **Usage**:
+
 ```python
 from _table_maker import table_repr
 
@@ -130,6 +146,7 @@ table = table_repr(data, style='markdown')
 ```
 
 **Key Features**:
+
 - Supports multiple border styles (double, heavy, light, markdown)
 - Auto-calculates column widths
 - Configurable padding and headers
@@ -140,14 +157,17 @@ table = table_repr(data, style='markdown')
 These scripts integrate with the documentation build process through the Makefile:
 
 1. **Full builds** (`make html`):
+
    - Runs `prep_docs.py` which executes all scripts
    - Generates all images and documentation files
 
-2. **Fast builds** (`make slimfast`):
+1. **Fast builds** (`make slimfast`):
+
    - May use `--stubs` mode for quicker iteration
    - Skips time-consuming generation tasks
 
-3. **Gallery builds** (`make slimgallery`):
+1. **Gallery builds** (`make slimgallery`):
+
    - May trigger `autogenerate_gui_images.py` for GUI screenshots
 
 ## Development Notes
@@ -157,9 +177,9 @@ These scripts integrate with the documentation build process through the Makefil
 When adding a new documentation generation script:
 
 1. Follow the existing pattern of supporting `--stubs` mode for fast builds
-2. Import and call your script from `prep_docs.py`
-3. Generate content in appropriate documentation directories
-4. Use relative imports for shared utilities like `_table_maker`
+1. Import and call your script from `prep_docs.py`
+1. Generate content in appropriate documentation directories
+1. Use relative imports for shared utilities like `_table_maker`
 
 ### Debugging
 
@@ -170,6 +190,7 @@ When adding a new documentation generation script:
 ### Dependencies
 
 Most scripts require:
+
 - A working napari installation with Qt backend
 - Access to napari source code
 - Additional tools like pydeps for architecture documentation
@@ -197,6 +218,7 @@ docs/
 ## Maintenance
 
 These scripts should be updated when:
+
 - New GUI components are added to napari
 - Event systems are modified
 - Preferences are added or changed
@@ -205,7 +227,7 @@ These scripts should be updated when:
 
 Regular testing ensures the documentation stays synchronized with the codebase.
 
----
+______________________________________________________________________
 
 ## Attribution