From 5def3d31470c1b3c12400d0cc376b6bf6128a91f Mon Sep 17 00:00:00 2001
From: Dimitri Yatsenko <dimitri.yatsenko@gmail.com>
Date: Tue, 27 Jan 2026 17:03:48 -0600
Subject: [PATCH] docs: Add programmatic config access and override syntax

- Add "Programmatic Access" section to configuration reference
- Document dot notation for reading/writing settings
- Explain double underscore syntax for nested settings in override()
- Clarify that display__diagram_direction maps to display.diagram_direction

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/reference/configuration.md | 41 ++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/reference/configuration.md b/src/reference/configuration.md
index 2102bed3..74e86745 100644
--- a/src/reference/configuration.md
+++ b/src/reference/configuration.md
@@ -241,6 +241,47 @@ export DJ_PASS=secret
 
 **Note:** Per-store credentials must be configured in `datajoint.json` or `.secrets/` — environment variable overrides are not supported for nested store configurations.
 
+## Programmatic Access
+
+### Reading and Writing Settings
+
+Access settings using dot notation on `dj.config`:
+
+```python
+import datajoint as dj
+
+# Read settings
+print(dj.config.database.host)
+print(dj.config.display.diagram_direction)
+
+# Write settings
+dj.config.database.host = "mysql.example.com"
+dj.config.display.diagram_direction = "TB"
+```
+
+### Temporary Overrides
+
+Use `dj.config.override()` to temporarily change settings within a context:
+
+```python
+with dj.config.override(safemode=False):
+    # safemode is False here
+    (Table & key).delete()
+# safemode is restored to original value
+```
+
+**Nested settings syntax:** Since Python doesn't allow dots in keyword argument names, use double underscores (`__`) to access nested settings in `override()`:
+
+```python
+# These are equivalent:
+dj.config.display.diagram_direction = "TB"  # direct assignment
+
+with dj.config.override(display__diagram_direction="TB"):  # in override()
+    ...
+```
+
+The double underscore maps to the dot-notation path: `display__diagram_direction` → `display.diagram_direction`.
+
 ## API Reference
 
 See [Settings API](../api/datajoint/settings.md) for programmatic access.