docs: Add documents for AI configs

Author: payamnj

django_email_learning/ai/language_models.py

@@ -4,10 +4,36 @@
 
 
 class LanguageModel(Enum):
+    """Supported AI text-editing models.
+
+    Each enum value maps to:
+
+    - ``model_name``: The provider model identifier sent to the AI API.
+    - ``adapter_class``: The adapter that knows how to call that provider.
+
+    The project currently ships with OpenAI-backed models only.
+
+    .. note::
+       These models are used when
+       ``DJANGO_EMAIL_LEARNING['AI']['TEXT_EDITING_MODEL']`` is configured.
+       AI configuration is optional and only required when using AI editing
+       features.
+    """
+
     GPT_4O_MINI = ("gpt-4o-mini", OpenAiAdapter)
+    """OpenAI GPT-4o mini model (balanced quality and speed)."""
+
     GPT_5_NANO = ("gpt-5-nano", OpenAiAdapter)
+    """OpenAI GPT-5 nano model (smallest and fastest GPT-5 variant)."""
+
     GPT_5_MINI = ("gpt-5-mini", OpenAiAdapter)
+    """OpenAI GPT-5 mini model (higher quality than nano, still efficient)."""
 
     def __init__(self, model_name: str, adapter_class: type[AiServiceProtocol]) -> None:
+        """Attach provider metadata to each model enum value.
+
+        :param model_name: External model name used by the AI provider API.
+        :param adapter_class: Adapter implementing :class:`AiServiceProtocol`.
+        """
         self.model_name = model_name
         self.adapter_class = adapter_class

docs/source/conf.py

@@ -13,7 +13,10 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinxcontrib.googleanalytics"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinxcontrib.googleanalytics",
+]
 
 googleanalytics_id = "G-67JHEC135G"
 googleanalytics_enabled = True

docs/source/index.rst

@@ -28,6 +28,7 @@ Django Email Learning documentation
    :maxdepth: 2
    :caption: Technical Reference
 
+   technical/ai-configuration
    technical/management-commands
 
 

docs/source/installation.rst

@@ -26,6 +26,12 @@ Installation Steps
 
        pip install django-email-learning
 
+   If you want to use AI editing tools, install with the AI optional extra:
+
+   .. code-block:: bash
+
+       pip install 'django-email-learning[ai]'
+
 2. **Add to INSTALLED_APPS**
 
    Add 'django_email_learning' to your INSTALLED_APPS in settings.py:
@@ -181,6 +187,50 @@ Optional configuration for branding assets in the platform header.
         },
     }
 
+**AI**
+
+Optional configuration for AI-powered text editing features.
+
+- Configure this only if you have an OpenAI account and want to use AI edit tools.
+- If you do not use AI features, you can omit ``AI`` entirely.
+- Install AI dependencies with ``pip install 'django-email-learning[ai]'``.
+- Add ``'django_email_learning.ai'`` to ``INSTALLED_APPS`` when using AI tools.
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # ... your other apps
+        'django_email_learning',
+        'django_email_learning.ai',
+        # ... more apps
+    ]
+
+Available keys:
+
+- ``OPENAI_API_KEY``: OpenAI API key used for AI requests.
+- ``TEXT_EDITING_MODEL``: OpenAI model name used by text editing.
+
+Currently supported built-in models are:
+
+- ``gpt-4o-mini``
+- ``gpt-5-nano``
+- ``gpt-5-mini``
+
+.. code-block:: python
+
+    from django_email_learning.ai.language_models import LanguageModel
+
+    DJANGO_EMAIL_LEARNING = {
+        'SITE_BASE_URL': 'https://yourdomain.com',
+        'ENCRYPTION_SECRET_KEY': 'your-very-long-random-string',
+        'AI': {
+            'OPENAI_API_KEY': os.environ.get('OPENAI_API_KEY'),
+            'TEXT_EDITING_MODEL': LanguageModel.GPT_4O_MINI.model_name,
+        },
+    }
+
+See `AI Configuration <technical/ai-configuration.html>`_ for full details.
+
 Email Backend Configuration
 ---------------------------
 

docs/source/technical/ai-configuration.rst

@@ -0,0 +1,69 @@
+AI Configuration
+================
+
+Django Email Learning supports optional AI-powered text editing features.
+
+If you do not use AI editing tools, you can omit the ``AI`` section entirely.
+
+Prerequisites
+-------------
+
+Before configuring AI settings, install the AI optional dependencies:
+
+.. code-block:: bash
+
+    pip install 'django-email-learning[ai]'
+
+Then include the AI app in ``INSTALLED_APPS``:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # ... your other apps
+        'django_email_learning',
+        'django_email_learning.ai',
+        # ... more apps
+    ]
+
+Settings
+--------
+
+Configure AI under ``DJANGO_EMAIL_LEARNING['AI']`` in your Django ``settings.py``.
+
+.. code-block:: python
+
+    from django_email_learning.ai.language_models import LanguageModel
+
+    DJANGO_EMAIL_LEARNING = {
+        'SITE_BASE_URL': 'https://yourdomain.com',
+        'ENCRYPTION_SECRET_KEY': 'your-very-long-random-string',
+        'AI': {
+            'OPENAI_API_KEY': os.environ.get('OPENAI_API_KEY'),
+            'TEXT_EDITING_MODEL': LanguageModel.GPT_4O_MINI.model_name,
+        },
+    }
+
+``OPENAI_API_KEY``
+~~~~~~~~~~~~~~~~~~
+
+API key used for OpenAI requests.
+
+- Required only when you want to use AI editing features.
+- Keep this value in environment variables or a secure secret manager.
+
+``TEXT_EDITING_MODEL``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Model name used by AI text editing features.
+
+- Value should match one of the names exposed by ``LanguageModel``.
+- Defaults can be set in your own project settings.
+
+Available Models
+----------------
+
+The package currently provides OpenAI-backed models:
+
+- ``gpt-4o-mini``
+- ``gpt-5-nano``
+- ``gpt-5-mini``