[M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks

[Gorkowski]

Description

Set up the Jupytext paired sync infrastructure for the pilot notebooks in Activity/ and Gas_Phase/ directories. This phase creates the configuration files needed before converting notebooks to paired format.

Context

Part of: M3: Jupytext Notebook Sync Migration (Pilot)

This is Phase 1 of the Jupytext pilot migration. The goal is to enable LLM-friendly notebook editing by pairing .ipynb files with .py:percent files that can be linted, type-checked, and have readable diffs.

Value:

• Enable ruff/mypy linting on example code
• Clean PR diffs instead of JSON noise
• Standard git merge conflict resolution
• Foundation for pilot notebook conversion

Scope

Estimated Lines of Code: ~30 lines of configuration changes
Complexity: Low (configuration only, no code)

Files to Create:

• jupytext.toml (~5 LOC)

Files to Modify:

• pyproject.toml (~15 LOC changes to [tool.ruff] section)
• mkdocs.yml (~2 LOC addition to exclude_docs)
• .gitignore (~2 LOC addition)

Acceptance Criteria

Core Implementation

• Create jupytext.toml at repository root with pairing rules:

  # Jupytext configuration for particula
  # Pairs notebooks in docs/Examples with percent-format Python scripts
  
  [formats]
  "docs/Examples/**/*.ipynb" = "ipynb,py:percent"

• Update pyproject.toml [tool.ruff] section:

  # UPDATE src to include docs/Examples
  src = ["particula", "docs/Examples"]
  include = ["particula/**/*.py", "docs/Examples/**/*.py"]
  
  # Keep existing extend-exclude unchanged:
  extend-exclude = [
    "**/*.ipynb",
  ]

• Add per-file-ignores for example scripts in pyproject.toml:

  [tool.ruff.lint.per-file-ignores]
  "*_test.py" = ["S101", "E721", "B008"]
  "docs/Examples/**/*.py" = ["D100", "D103", "INP001"]

  Note: D100 = missing module docstring, D103 = missing function docstring, INP001 = implicit namespace package (no __init__.py)

• Update mkdocs.yml exclude_docs section:

  exclude_docs: |
    .assets/
    Examples/**/*.py

• Add to .gitignore (after line 103, Jupyter Notebook section):

  # Jupyter notebook backups (created by run_notebook tool)
  *.ipynb.bak

Validation (No separate tests - configuration validation)

• jupytext.toml exists and is valid TOML
• ruff check particula/ still passes (existing code not affected)
• ruff check docs/Examples/Activity/ docs/Examples/Gas_Phase/ runs without config errors (may have linting issues in existing .py files - that's expected)
• mkdocs build succeeds without errors

Technical Notes

Why These Specific Ignores?

The docs/Examples/**/*.py ignores are intentional:

• D100 (missing module docstring): Example scripts don't need module docstrings
• D103 (missing function docstring): Example code prioritizes brevity
• INP001 (implicit namespace package): Examples aren't importable packages

Current pyproject.toml State

Currently (lines 57-86):

[tool.ruff]
line-length = 80
fix = true
src = ["particula"]
include = ["particula/**/*.py"]
extend-exclude = [
  "**/*.ipynb",
]

[tool.ruff.lint.per-file-ignores]
"*_test.py" = ["S101", "E721", "B008"]

Current mkdocs.yml State

Currently (lines 8-9):

exclude_docs: |
  .assets/

Current .gitignore State

Line 102-103 has:

# Jupyter Notebook
.ipynb_checkpoints

Add backup entry after this section.

Validation Commands

# Verify jupytext.toml is valid
python -c "import tomllib; tomllib.load(open('jupytext.toml', 'rb'))"

# Verify ruff config works
ruff check particula/ --select=E --max-errors=0 || echo "Expected: passes"
ruff check docs/Examples/Activity/ --select=E || echo "May have linting issues"

# Verify mkdocs builds
mkdocs build --strict 2>&1 | head -20

References

Maintenance Plan:

• adw-docs/dev-plans/maintenance/M3-jupytext-notebook-sync.md - Full migration plan

Configuration References:

• pyproject.toml (lines 57-86) - Current ruff config
• mkdocs.yml (lines 8-9) - Current exclude_docs
• .gitignore (lines 102-103) - Jupyter section

Documentation:

• adw-docs/documentation_guide.md (lines 341-534) - Jupytext workflow docs

[Gorkowski]

[ADW-AGENTS] # 🤖 ADW Workflow Status

Description: Patch workflow: quick fixes (plan → build → validate → test → format → ship)

ADW ID: 058d6592
Current Phase: Workflow completed successfully
Started: 2026-01-30T17:49:11.472437Z
Last Update: 2026-01-30T18:26:59.124624Z

Current Status

✅ Workflow completed in 37m 45s

Workflow Plan

• ✅ Generate Multi-Review Implementation Plan (at 2026-01-30T17:55:04.884172Z)
• ✅ Build Implementation (at 2026-01-30T17:57:30.803904Z)
• ✅ Validate Implementation and Fix Gaps (at 2026-01-30T18:14:30.200429Z)
• ✅ Run Tests (at 2026-01-30T18:24:02.925316Z)
• ✅ Format Code and Add Docstrings (at 2026-01-30T18:24:41.839866Z)
• ✅ Ship Implementation (at 2026-01-30T18:26:57.394275Z)

📋 Recent Activity

[2026-01-30T17:57:30.803922Z] Completed step 2/6: Build Implementation
[2026-01-30T17:57:32.460024Z] Starting step 3/6: Validate Implementation and Fix Gaps
[2026-01-30T18:14:30.200445Z] Completed step 3/6: Validate Implementation and Fix Gaps
[2026-01-30T18:14:31.838842Z] Starting step 4/6: Run Tests
[2026-01-30T18:24:02.925336Z] Completed step 4/6: Run Tests
[2026-01-30T18:24:04.567621Z] Starting step 5/6: Format Code and Add Docstrings
[2026-01-30T18:24:41.839884Z] Completed step 5/6: Format Code and Add Docstrings
[2026-01-30T18:24:43.680926Z] Starting step 6/6: Ship Implementation
[2026-01-30T18:26:57.394291Z] Completed step 6/6: Ship Implementation
[2026-01-30T18:26:59.123022Z] Workflow patch finished: 6/6 steps completed

🔍 Archived Updates

[2026-01-30T17:49:11.548373Z] Workflow patch started with 6 steps
[2026-01-30T17:49:13.455672Z] Starting step 1/6: Generate Multi-Review Implementation Plan
[2026-01-30T17:55:04.884191Z] Completed step 1/6: Generate Multi-Review Implementation Plan
[2026-01-30T17:55:06.521989Z] Starting step 2/6: Build Implementation

---

This comment is automatically updated as the workflow progresses