Add module docstrings to scripts

docs/_scripts/README.md

@@ -0,0 +1,213 @@
+# napari Documentation Scripts
+
+This directory contains Python scripts that automate various aspects of the napari documentation build process. These scripts generate content, capture screenshots, and analyze the codebase to keep the documentation synchronized with the actual implementation.
+
+## 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
+- Analyze and document UI architecture
+- Generate formatted tables for documentation
+
+## Scripts
+
+### prep_docs.py
+
+**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
+- Manages the overall documentation preparation workflow
+
+### autogenerate_gui_images.py
+
+**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
+- Handles proper rendering timing with Qt
+
+### update_event_docs.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
+- Merges common events across similar layer types
+
+### update_preference_docs.py
+
+**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
+- Includes programmatic access patterns for each setting
+
+### update_ui_sections_docs.py
+
+**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`
+  - `application_status_bar_ui.md`
+  - `application_menus_ui.md`
+  - `viewer_ui.md`
+  - `dialogs_ui.md`
+  - `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
+
+**Purpose**: Utility module for creating formatted ASCII/Markdown tables.
+
+**Usage**:
+```python
+from _table_maker import table_repr
+
+data = [['Name', 'Description'], ['event1', 'First event']]
+table = table_repr(data, style='markdown')
+```
+
+**Key Features**:
+- Supports multiple border styles (double, heavy, light, markdown)
+- Auto-calculates column widths
+- Configurable padding and headers
+- Used by other scripts for table generation
+
+## Build Integration
+
+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`):
+   - May use `--stubs` mode for quicker iteration
+   - Skips time-consuming generation tasks
+
+3. **Gallery builds** (`make slimgallery`):
+   - May trigger `autogenerate_gui_images.py` for GUI screenshots
+
+## Development Notes
+
+### Adding New Scripts
+
+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`
+
+### Debugging
+
+- Run scripts individually to debug specific documentation generation
+- Use `--stubs` mode to test script structure without full generation
+- Check generated files in their respective output directories
+
+### Dependencies
+
+Most scripts require:
+- A working napari installation with Qt backend
+- Access to napari source code
+- Additional tools like pydeps for architecture documentation
+
+## Output Directories
+
+Generated content is organized as follows:
+
+```
+docs/
+├── images/_autogenerated/     # GUI screenshots
+│   ├── widgets/
+│   ├── menus/
+│   ├── popups/
+│   ├── regions/
+│   └── preferences/
+├── guides/                    # Generated guides
+│   ├── _viewer_events.md
+│   ├── _layerlist_events.md
+│   ├── _layer_events.md
+│   └── preferences.md
+└── developers/architecture/ui_sections/  # UI architecture docs
+```
+
+## Maintenance
+
+These scripts should be updated when:
+- New GUI components are added to napari
+- Event systems are modified
+- Preferences are added or changed
+- UI architecture is refactored
+- Documentation structure changes
+
+Regular testing ensures the documentation stays synchronized with the codebase.
+
+---
+
+## Attribution
+
+This document was drafted with the assistance of Claude Code.
+The output was reviewed and edited for accuracy and clarity.

docs/_scripts/_table_maker.py

@@ -1,3 +1,54 @@
+"""Table generation utilities for napari documentation.
+
+This module provides functionality to create formatted ASCII and Markdown tables
+for use in the napari documentation. It supports multiple border styles and
+customizable formatting options.
+
+The primary use case is generating well-formatted tables for event documentation,
+preferences documentation, and other tabular data that needs to be displayed in
+the napari documentation.
+
+Example:
+    Basic usage with markdown style (default)::
+
+        >>> from _table_maker import table_repr
+        >>> data = [
+        ...     ['Event', 'Description', 'Type'],
+        ...     ['theme', 'Theme changed', 'str'],
+        ...     ['title', 'Title changed', 'str']
+        ... ]
+        >>> print(table_repr(data, header=data[0], style='markdown'))
+
+    Using different border styles::
+
+        >>> # Double-line borders
+        >>> print(table_repr(data, style='double'))
+
+        >>> # Heavy borders
+        >>> print(table_repr(data, style='heavy'))
+
+        >>> # Light borders
+        >>> print(table_repr(data, style='light'))
+
+Attributes:
+    STYLES (dict): Dictionary of border style definitions. Each style contains:
+        - TOP: Characters for top border (left corner, separator, right corner, line)
+        - MID: Characters for middle borders (left, separator, right, line)
+        - BOT: Characters for bottom border (left corner, separator, right corner, line)
+        - V: Characters for vertical borders (outer, inner)
+
+Available styles:
+    - 'double': Double-line box drawing characters (╔═╤═╗)
+    - 'heavy': Heavy box drawing characters (┏━┯━┓)
+    - 'light': Light box drawing characters (┌─┬─┐)
+    - 'markdown': Markdown-compatible table format (| | |)
+
+Attribution
+-----------
+This docstring was drafted with the assistance of Claude Code.
+The output was reviewed and edited for accuracy and clarity.
+"""
+
 import numpy as np
 
 STYLES = {