docs: Add singleton tables documentation

conftest.py

@@ -0,0 +1,35 @@
+"""
+Pytest configuration for notebook tests.
+
+Configures DataJoint from environment variables before any tests run.
+This separates configuration from workflow execution.
+
+Usage:
+    # MySQL (default)
+    DJ_HOST=localhost DJ_USER=root DJ_PASS=tutorial pytest --nbmake ...
+
+    # PostgreSQL
+    DJ_HOST=localhost DJ_PORT=5432 DJ_USER=datajoint DJ_PASS=tutorial DJ_BACKEND=postgresql pytest --nbmake ...
+"""
+
+import os
+
+
+def pytest_configure(config):
+    """Configure DataJoint from environment variables before tests run."""
+    import datajoint as dj
+
+    # Database connection settings
+    if os.getenv('DJ_HOST'):
+        dj.config['database.host'] = os.getenv('DJ_HOST')
+    if os.getenv('DJ_PORT'):
+        dj.config['database.port'] = int(os.getenv('DJ_PORT'))
+    if os.getenv('DJ_USER'):
+        dj.config['database.user'] = os.getenv('DJ_USER')
+    if os.getenv('DJ_PASS'):
+        dj.config['database.password'] = os.getenv('DJ_PASS')
+    if os.getenv('DJ_BACKEND'):
+        dj.config['database.backend'] = os.getenv('DJ_BACKEND')
+
+    # Display settings for notebooks
+    dj.config['display.limit'] = 8

mkdocs.yaml

@@ -86,6 +86,8 @@ nav:
           - Migrate to 2.0: how-to/migrate-to-v20.md
           - Alter Tables: how-to/alter-tables.md
           - Backup and Restore: how-to/backup-restore.md
+      - Testing:
+          - Testing Best Practices: how-to/testing.md
   - Reference:
       - reference/index.md
       - Specifications:

src/explanation/computation-model.md

@@ -106,10 +106,10 @@ Each auto-populated table has an associated jobs table:
 Segmentation.jobs()
 
 # View errors
-Segmentation.jobs & 'status = "error"'
+Segmentation.jobs & "status = 'error'"
 
 # Clear errors to retry
-(Segmentation.jobs & 'status = "error"').delete()
+(Segmentation.jobs & "status = 'error'").delete()
 ```
 
 ### Parallel Execution
@@ -134,13 +134,13 @@ Jobs are reserved atomically—no two workers process the same key.
 Segmentation.populate(suppress_errors=True)
 
 # Check what failed
-errors = (Segmentation.jobs & 'status = "error"').to_dicts()
+errors = (Segmentation.jobs & "status = 'error'").to_dicts()
 
 # Clear specific error to retry
 (Segmentation.jobs & error_key).delete()
 
 # Clear all errors
-(Segmentation.jobs & 'status = "error"').delete()
+(Segmentation.jobs & "status = 'error'").delete()
 ```
 
 ## Imported vs. Computed

src/explanation/query-algebra.md

@@ -34,13 +34,13 @@ Filter entities based on conditions.
 
 ```python
 # Mice born after 2024
-Mouse & 'date_of_birth > "2024-01-01"'
+Mouse & "date_of_birth > '2024-01-01'"
 
 # Sessions for a specific mouse
 Session & {'mouse_id': 42}
 
 # Sessions matching a query
-Session & (Mouse & 'strain = "C57BL/6"')
+Session & (Mouse & "strain = 'C57BL/6'")
 ```
 
 ### Exclude (`-`)
@@ -221,7 +221,7 @@ Operators compose freely:
 ```python
 # Complex query
 result = (
-    (Mouse & 'strain = "C57BL/6"')  # Filter mice
+    (Mouse & "strain = 'C57BL/6'")  # Filter mice
     * Session                        # Join sessions
     * Scan                           # Join scans
     .proj('scan_date', 'depth')      # Select attributes

src/how-to/delete-data.md

@@ -11,7 +11,7 @@ Delete rows matching a restriction:
 (Subject & {'subject_id': 'M001'}).delete()
 
 # Delete with condition
-(Session & 'session_date < "2024-01-01"').delete()
+(Session & "session_date < '2024-01-01'").delete()
 ```
 
 ## Cascade Behavior
@@ -141,14 +141,14 @@ Delete without cascade (fails if dependent rows exist):
 ### By Condition
 
 ```python
-(Trial & 'outcome = "miss"').delete()
+(Trial & "outcome = 'miss'").delete()
 ```
 
 ### By Join
 
 ```python
 # Delete trials from sessions before 2024
-old_sessions = Session & 'session_date < "2024-01-01"'
+old_sessions = Session & "session_date < '2024-01-01'"
 (Trial & old_sessions).delete()
 ```
 

src/how-to/handle-errors.md

@@ -55,7 +55,7 @@ Target specific failed jobs:
 
 ```python
 # Clear one error
-(ProcessedData.jobs & key & 'status="error"').delete()
+(ProcessedData.jobs & key & "status='error'").delete()
 
 # Retry just that key
 ProcessedData.populate(key, reserve_jobs=True)

src/how-to/index.md

@@ -52,3 +52,7 @@ they assume you understand the basics and focus on getting things done.
 - [Migrate to v2.0](migrate-to-v20.md) — Upgrading existing pipelines
 - [Alter Tables](alter-tables.md) — Schema evolution
 - [Backup and Restore](backup-restore.md) — Data protection
+
+## Testing
+
+- [Testing Best Practices](testing.md) — Integration testing with pytest

src/how-to/migrate-to-v20.md

@@ -385,7 +385,7 @@ def test_query_patterns(test_schema):
     assert len(mice) == 1
 
     # Test restriction
-    male_mice = Mouse & 'sex="M"'
+    male_mice = Mouse & "sex='M'"
     assert len(male_mice) == 1
 ```
 
@@ -417,7 +417,7 @@ def test_full_pipeline(test_schema):
     assert len(Analysis()) > 0
 
     # 4. Test queries work
-    alice_sessions = Session & 'experimenter="Alice"'
+    alice_sessions = Session & "experimenter='Alice'"
     assert len(alice_sessions) == 1
 ```