Update docs

Author: jacklinke

README.md

@@ -73,15 +73,15 @@ In a SaaS environment, one size doesn't fit all. Tenants often have unique needs
 
 ### 5. Other Use-Cases
 
-See additional [use cases](https://django-tenant-options.readthedocs.io/en/latest/usecases/) in the documentation for more inspiration.
+See [the options cookbook](https://django-tenant-options.readthedocs.io/en/latest/optionscookbook.html) in the documentation for more inspiration.
 
 ## Example Implementation
 
 Consider a scenario where your SaaS provides project management tools for businesses. Each User is associated with a Tenant, and can create Tasks. You want each tenant to be able to customize the available task "priorities" and "status" provided in user-facing task tracking forms. Here’s how you can implement this with `django-tenant-options`.
 
 > 🟩 Note
 >
-> See the [example project](./exampleproject.md) for the more detailed demonstration of how to set up a multi-tenant application with custom options using `django-tenant-options`.
+> See the [example project](https://django-tenant-options.readthedocs.io/en/latest/exampleproject.html) for the more detailed demonstration of how to set up a multi-tenant application with custom options using `django-tenant-options`.
 
 ### Existing Models
 
@@ -116,12 +116,15 @@ class Task(models.Model):
 
 Each Set of options in `django-tenant-options` is defined by two models: an `Option` model, which stores all mandatory, optional, and custom options, and a `Selection` model, which identifies which options are currently associated with a tenant.
 
-With a `Tenant` model and a `Task` model in your project, you can implement the `TaskPriorityOption` and `TaskPrioritySelection` models as follows:
+With a `Tenant` model and a `Task` model in your project, you can implement the `TaskPriorityOption` and `TaskPrioritySelection` models, which inherit from [`AbstractOption`](https://django-tenant-options.readthedocs.io/en/latest/reference.html#django_tenant_options.models.AbstractOption) and [`AbstractSelection`](https://django-tenant-options.readthedocs.io/en/latest/reference.html#django_tenant_options.models.AbstractSelection) respectively.
+
+In each Option model, you can define the `default_options` dictionary for task priorities or status, including which options are mandatory and which are optional. In this example, "High" and "Low" priorities are mandatory for all tenants (and users will always see these options in forms), while "Critical" and "Medium" priorities are optional for selection by tenants. Tenants can also create custom priorities as needed.
 
 ```python
 from django.db import models
 
-from django_tenant_options.models import AbstractOption, AbstractSelection, OptionType
+from django_tenant_options.models import AbstractOption, AbstractSelection
+from django_tenant_options.choices import OptionType
 
 
 class TaskPriorityOption(AbstractOption):
@@ -132,7 +135,7 @@ class TaskPriorityOption(AbstractOption):
         "Critical": {"option_type": OptionType.OPTIONAL},
         "High": {"option_type": OptionType.MANDATORY},
         "Medium": {"option_type": OptionType.OPTIONAL},
-        "Low": {"option_type": OptionType.MANDATORY},
+        "Low": {},  # If no option_type is provided, it defaults to OptionType.MANDATORY
     }
 
     class Meta(AbstractOption.Meta):
@@ -198,22 +201,60 @@ class Task(models.Model):
 
 ### Forms
 
-`django-tenant-options` provides a set of forms to manage the options and selections for each tenant. You can use these forms in your views to allow tenants to customize their options.
+`django-tenant-options` provides a set of form mixins and fields to manage the options and selections for each tenant. You can use these forms in your views to allow tenants to customize their options.
+
+- `OptionCreateFormMixin` and `OptionUpdateFormMixin` are provided to create and update Options.
+- `SelectionForm` is used to manage the Selections associated with a tenant.
+- `UserFacingFormMixin` is provided to ensures ForeignKey fields to an `AbstractOption` subclass are populated with the correct tenant Selections.
+- `OptionsModelMultipleChoiceField` is a customized `ModelMultipleChoiceField` that retrieves the Options and also displays the option type associated with each Option.
+
+You are encouraged to extend these Mixins and Fields to suit your project's needs.
 
 ```python
 from django import forms
 
-from django_tenant_options.forms import OptionForm, SelectionForm
+from django_tenant_options.forms import OptionCreateFormMixin, OptionUpdateFormMixin, SelectionForm, UserFacingFormMixin
+from example.models import Task, TaskPriorityOption, TaskPrioritySelection
+
+
+class TaskForm(UserFacingFormMixin, forms.ModelForm):
+    """Form for creating and updating a Task."""
+    class Meta:
+        model = Task
+        fields = "__all__"
+
 
+class TaskPriorityOptionCreateForm(OptionCreateFormMixin, forms.ModelForm):
+    """Form for creating a TaskPriorityOption."""
+    class Meta:
+        model = TaskPriorityOption
+        fields = "__all__"
+
+
+class TaskPriorityOptionUpdateForm(OptionUpdateFormMixin, forms.ModelForm):
+    """Form for updating a TaskPriorityOption."""
+    class Meta:
+        model = TaskPriorityOption
+        fields = "__all__"
+
+
+class TaskPrioritySelectionForm(SelectionForm):
+    """Form for selecting TaskPriorityOptions."""
+    class Meta:
+        model = TaskPrioritySelection
 ```
 
-### Management Commands
+### Views, Templates, and URLs
+
+Views, Templates, and URLs can be implemented as needed to allow tenants to manage their options. Views tfor forms that use `OptionCreateFormMixin`, `OptionUpdateFormMixin`, and `SelectionForm` must pass the tenant instance to the form's `tenant` attribute.
+
+## Management Commands
 
 `django-tenant-options` provides management commands for easy maintenance:
 
-- **`listoptions`**: Lists all available options in the database.
-- **`syncoptions`**: Synchronizes the `defaults` in each model with the database when a change in the model has been made. Should always be run after any migrations have been completed.
-- **`maketriggers`**: Creates database trigger migrations to ensure there can never be mismatch between a Tenant and an associated Option.
+- **[`listoptions`](https://django-tenant-options.readthedocs.io/en/latest/reference.html#listoptions)**: Lists all available options in the database.
+- **[`syncoptions`](https://django-tenant-options.readthedocs.io/en/latest/reference.html#syncoptions)**: Synchronizes the `default_options` in each model with the database when a change in the model has been made. Should always be run after any migrations have been completed.
+- **[`maketriggers`](https://django-tenant-options.readthedocs.io/en/latest/reference.html#maketriggers-options)**: Creates database trigger migrations to ensure there can never be mismatch between a Tenant and an associated Option.
 
 ```bash
 python manage.py syncoptions

docs/index.md

@@ -14,7 +14,7 @@ usage
 terminology
 exampleproject
 reference
-usecases
+optionscookbook
 contributing
 Code of Conduct <codeofconduct>
 License <license>

docs/usecases.md docs/optionscookbook.mddocs/usecases.md renamed to docs/optionscookbook.md

@@ -1,8 +1,8 @@
-# Example Use Cases
+# The Options Cookbook
 
 To help you get started, we have compiled a list of common data categories and their recommended types. These categories can be used as a reference when setting up your options in a multi-tenant application.
 
-In general, for industry-standard categories or statuses, we recommend providing options as mandatory (always displayed in a tenant's user-facing form) or optional (each tenant can choose whether it is displayed to users as an option they can select). For categories or statuses that are specific to a tenant's business or industry, they can create custom options to meet their unique needs.
+In general, for industry-standard categories or statuses, we recommend providing options as mandatory (always displayed in a tenant's user-facing form) or optional (each tenant can choose whether it is displayed to users as an option they can select). For categories or statuses that are specific to a tenant's business or organization, they can create custom options to meet their unique needs.
 
 > 🟩 Note
 >
@@ -210,6 +210,37 @@ In general, for industry-standard categories or statuses, we recommend providing
 | Hybrid drive                   | Tenant-Specific Custom Option  |
 | Rock carving storage           | Tenant-Specific Custom Option  |
 
+## Infrastructure - Road Types
+
+| Option            | Recommended Type               |
+|-------------------|--------------------------------|
+| Highway           | Mandatory                      |
+| Street            | Mandatory                      |
+| Avenue            | Mandatory                      |
+| Lane              | Mandatory                      |
+| Boulevard         | Optional                       |
+| Alley             | Optional                       |
+| Freeway           | Optional                       |
+| Expressway        | Optional                       |
+| Parkway           | Optional                       |
+| Bike path         | Tenant-Specific Custom Option  |
+
+## Insurance - Policy Types
+
+| Option                    | Recommended Type               |
+|---------------------------|--------------------------------|
+| Life                      | Mandatory                      |
+| Health                    | Mandatory                      |
+| Auto                      | Mandatory                      |
+| Homeowners                | Mandatory                      |
+| Renters                   | Mandatory                      |
+| Disability                | Optional                       |
+| Long-term care            | Optional                       |
+| Travel                    | Optional                       |
+| Pet                       | Optional                       |
+| Business                  | Optional                       |
+| Alien abduction           | Tenant-Specific Custom Option  |
+
 ## Learning Management System (LMS) - Course Categories & Grading Schemes
 
 | Option                    | Recommended Type               |

docs/usage.md

@@ -26,4 +26,4 @@ DJANGO_TENANT_OPTIONS = {
 }
 ```
 
-For more information on the available settings, see the [`app_settings.py` reference](./reference.md#module-django_tenant_options.app_settings).
+For more information on the available settings, see the [`app_settings.py` reference](https://django-tenant-options.readthedocs.io/en/latest/reference.html#module-django_tenant_options.app_settings).