diff --git a/docs/_scripts/update_preference_docs.py b/docs/_scripts/update_preference_docs.py
index ef60c7fef..69201d11a 100644
--- a/docs/_scripts/update_preference_docs.py
+++ b/docs/_scripts/update_preference_docs.py
@@ -20,7 +20,7 @@
 
 Starting with version 0.4.6, napari provides persistent settings.
 
-Settings are managed by getting the global settings object:
+Settings are managed by getting the global settings object and modifying settings:
 
 ```python
 from napari.settings import get_settings
@@ -30,38 +30,6 @@
 settings.appearance.theme = 'dark'
 ```
 
-## Sections
-
-The settings are grouped by sections and napari core provides the following:
-
-{%- for section, section_data in sections.items() %}
-
-### {{ section_data["title"]|upper }}
-
-{{ section_data["description"] }}
-
-{%   for fields in section_data["fields"] %}
-#### {{ fields["title"] }}
-
-*{{ fields["description"] }}*
-
-* <small>Access programmatically with `SETTINGS.{{ section }}.{{ fields["field"] }}`.</small>
-* <small>Type: `{{ fields["type"] }}`.</small>
-* <small>Default: `{{ fields["default"] }}`.</small>
-{% if fields["ui"] %}* <small>UI: This setting can be configured via the preferences dialog.</small>{% endif %}
-{%-   endfor -%}
-{% endfor %}
-
-**Support for plugin specific settings will be provided in an upcoming release.**
-
-## Changing settings programmatically
-
-```python
-from napari.settings import SETTINGS
-
-SETTINGS.appearance.theme = "light"
-```
-
 ## Reset to defaults via CLI
 
 To reset all napari settings to the default values:
@@ -90,6 +58,30 @@
 
 ![{{ reset }}]({{ images_path }}/preferences-reset.png)
 
+## Sections
+
+The settings are grouped by sections and napari core provides the following:
+
+{%- for section, section_data in sections.items() %}
+
+### {{ section_data["title"]|upper }}
+
+{{ section_data["description"] }}
+
+{%   for fields in section_data["fields"] %}
+#### {{ fields["title"] }}
+
+*{{ fields["description"] }}*
+
+* <small>Access programmatically with `SETTINGS.{{ section }}.{{ fields["field"] }}`.</small>
+* <small>Type: `{{ fields["type"] }}`.</small>
+* <small>Default: `{{ fields["default"] }}`.</small>
+{% if fields["ui"] %}* <small>UI: This setting can be configured via the preferences dialog.</small>{% endif %}
+{%-   endfor -%}
+{% endfor %}
+
+**Support for plugin specific settings will be provided in an upcoming release.**
+
 """
 
 
@@ -105,11 +97,25 @@ def generate_images():
     pref.show()
     QTimer.singleShot(1000, pref.close)
 
-    for idx, (name, field) in enumerate(NapariSettings.__fields__.items()):
+    # Collect all sections first
+    sections = [field.field_info.title or name
+                for name, field in NapariSettings.__fields__.items()
+                if isinstance(field.type_, ModelMetaclass)]
+    
+    # Process each section with proper timing
+    for idx, title in enumerate(sections):
+        # Set current index
         pref._stack.setCurrentIndex(idx)
+        pref._list.setCurrentRow(idx)
+        
+        # Process events to ensure UI has updated
+        app.processEvents()
+        
+        # Capture screenshot
         pixmap = pref.grab()
-        title = field.field_info.title or name
         pixmap.save(str(IMAGES_PATH / f"preferences-{title.lower()}.png"))
+    
+
 
     box = QMessageBox(
         QMessageBox.Icon.Question,