From 8563ba5ec6f6d44444a44967c4ad82a30fa45ef6 Mon Sep 17 00:00:00 2001
From: david <no@email>
Date: Sat, 2 Aug 2025 21:29:36 +0200
Subject: [PATCH] Add documentation around the usage of collection types as
 field types

---
 docs/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index 8ed47dd..7d13d58 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -105,6 +105,10 @@ The supported types are:
 * ``list``
 * ``dict``
 
+.. note::
+    To be able to use ``list`` and ``dict`` you need to set a widget and form field for these types as it is ambiguous what types shall be stored in the collection object.
+    You can do so with :setting:`CONSTANCE_ADDITIONAL_FIELDS` as explained below.
+
 For example, to force a value to be handled as a string:
 
 .. code-block:: python
@@ -165,6 +169,21 @@ Images and files are uploaded to ``MEDIA_ROOT`` by default. You can specify a su
 
 This will result in files being placed in ``media/constance`` within your ``BASE_DIR``. You can use deeper nesting in this setting (e.g. ``constance/images``) but other relative path components (e.g. ``../``) will be rejected.
 
+In case you want to store a list of ``int`` values in the constance config, a working setup is
+
+.. code-block:: python
+    
+    CONSTANCE_ADDITIONAL_FIELDS = {
+        list: ["django.forms.fields.JSONField", {"widget": "django.forms.Textarea"}],
+    }
+
+    CONSTANCE_CONFIG = {
+        'KEY': ([0, 10, 20], 'A list of integers', list),
+    }
+
+Make sure to use the ``JSONField`` for this purpose as user input in the admin page may be understood and saved as ``str`` otherwise.
+
+
 Ordered Fields in Django Admin
 ------------------------------