Remove ENABLE_AUTO_CONFIG setting and autoconfiguration functionality (#216)

* Remove ENABLE_AUTO_CONFIG setting and autoconfiguration functionality

* update changelog

* update readme

* reorg config docs

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,8 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+🚨 This release contains some breaking changes. See the Removed section for more information. 🚨
+
 ### Added
 
 - Added `get_component_names_used_in_template` method to ComponentRegistry to access component names used in a template
@@ -39,7 +41,9 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 ### Removed
 
 - Removed automatic component scanning at application startup for faster initialization
+- Removed `ENABLE_AUTO_CONFIG` setting and autoconfiguration functionality (moved to django-bird-autoconf plugin)
 - **Internal**: Removed `ComponentRegistry.discover_components` method.
+- **Internal**: Removed `AutoConfigurator` class used for automatic setting configuration
 
 ## [0.16.2]
 

README.md

@@ -43,11 +43,34 @@ High-flying components for perfectionists with deadlines.
     ]
     ```
 
-3. django-bird will automatically configure the necessary settings in your project.
-
-   If you need to customize the configuration or prefer to set up django-bird manually, you can set `DJANGO_BIRD["ENABLE_AUTO_CONFIG"] = False` in your settings.
-
-   For detailed instructions, please refer to the [Manual Setup](https://django-bird.readthedocs.io/configuration.html#manual-setup) section within the Configuration documentation.
+3. Set up django-bird in your project settings:
+
+   ```python
+   # Required: Add the asset finder to handle component assets
+   STATICFILES_FINDERS = [
+       "django.contrib.staticfiles.finders.FileSystemFinder",
+       "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+       "django_bird.staticfiles.BirdAssetFinder",
+   ]
+
+   # Optional: Add templatetags to builtins for convenience
+   # (otherwise you'll need to {% load django_bird %} in each template)
+   TEMPLATES = [
+       {
+           # ... other settings ...
+           "OPTIONS": {
+               "builtins": [
+                   "django_bird.templatetags.django_bird",
+               ],
+           },
+       }
+   ]
+   ```
+
+   For detailed instructions, please refer to the [Configuration](https://django-bird.readthedocs.io/configuration.html#configuration) section in the documentation.
+
+   > [!TIP]
+   > For automatic configuration, you can use the [django-bird-autoconf](https://pypi.org/project/django-bird-autoconf/) plugin.
 
 ## Getting Started
 

docs/assets.md

@@ -115,7 +115,7 @@ The `{% bird:css %}` tag will include CSS and the `[% bird:js %}` tag will inclu
 
 django-bird provides a custom staticfiles finder to serve component assets through Django's static files system. This allows you to collect all component assets using Django's `collectstatic` command and serve them efficiently in production.
 
-To enable the custom finder, `BirdAssetFinder` must be in the list in your `STATICFILES_FINDERS` setting. This should be handled if are allowing django-bird to configure your project. If you are manually configuring the library by [setting `ENABLE_AUTO_CONFIG = False` in your `DJANGO_BIRD` settings](configuration.md#enable_auto_config), you will need to add the finder by hand:
+To enable the custom finder, `BirdAssetFinder` must be in the list in your `STATICFILES_FINDERS` setting. If you aren't using the [django-bird-autoconf](https://pypi.org/project/django-bird-autoconf/) plugin, you will need to add the finder manually:
 
 ```{code-block} python
 :caption: settings.py

docs/configuration.md

@@ -1,8 +1,54 @@
 # Configuration
 
+## Django settings
+
+To use django-bird, you need to configure a few settings in your project:
+
+1. Add django-bird's static file finder to your STATICFILES_FINDERS.
+2. Add django-bird's template tags to Django's built-ins. **Note**: This is not required, but if you do not do this you will need to use `{% load django_bird %}` in any templates using components.
+
+```{admonition} Auto Configuration
+:class: tip
+
+For automatic configuration of these settings, you can use the [django-bird-autoconf](https://pypi.org/project/django-bird-autoconf/) plugin. This plugin will handle all the setup for you automatically.
+```
+
+The complete setup in your settings file should look like this:
+
+```{code-block} python
+:caption: settings.py
+
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve(strict=True).parent
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [
+            BASE_DIR / "templates",
+        ],
+        "OPTIONS": {
+            "builtins": [
+                "django_bird.templatetags.django_bird",
+            ],
+        },
+    }
+]
+
+STATICFILES_FINDERS = [
+    "django.contrib.staticfiles.finders.FileSystemFinder",
+    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+    "django_bird.staticfiles.BirdAssetFinder",
+]
+```
+
+This configuration ensures that django-bird's templatetags are available globally and component assets can be properly discovered.
 Configuration of django-bird is done through a `DJANGO_BIRD` dictionary in your Django settings.
 
-All settings are optional. Here is an example configuration with the types and default values shown:
+## Application settings
+
+All app settings are optional. Here is an example configuration with the types and default values shown:
 
 ```{code-block} python
 :caption: settings.py
@@ -11,18 +57,17 @@ from pathlib import Path
 
 DJANGO_BIRD = {
     "COMPONENT_DIRS": list[Path | str] = [],
-    "ENABLE_AUTO_CONFIG": bool = True,
     "ENABLE_BIRD_ATTRS": bool = True,
 }
 ```
 
-## `COMPONENT_DIRS`
+### `COMPONENT_DIRS`
 
 Additional directories to scan for components. Takes a list of paths relative to the base directory of your project's templates directory. A path can either be a `str` or `Path`.
 
 By default, django-bird will look for components in a `bird` directory. Any directories specified here will take precedence and take priority when performing template resolution for components.
 
-### Example
+#### Example
 
 Suppose you want to store your components in a `components` directory, you're using a third-party library that provides its own bird components, and you have an alternate templates directory.
 
@@ -59,49 +104,8 @@ With this setup, django-bird will search for components in the following order:
 
 The default `bird` directory will always be checked last, ensuring that your custom directories take precedence in template resolution.
 
-## `ENABLE_AUTO_CONFIG`
-
-django-bird requires a few settings to be setup in your project's `DJANGO_SETTINGS_MODULE` before it will work properly. django-bird will automatically take care of this, during the app's initialization in `django_bird.apps.AppConfig.ready`.
-
-If you would like to disable this behavior and perform the setup manually, setting `ENABLE_AUTO_CONFIG` to `False` will allow you to do so.
-
-### Manual Setup
-
-When `ENABLE_AUTO_CONFIG` is set to `False`, you need to manually configure the following:
-
-1. Add django-bird's template tags to Django's built-ins.
-
-The complete setup in your settings file should look like this:
-
-```{code-block} python
-:caption: settings.py
-
-from pathlib import Path
-
-BASE_DIR = Path(__file__).resolve(strict=True).parent
-
-DJANGO_BIRD = {
-    "ENABLE_AUTO_CONFIG": False,
-}
-
-TEMPLATES = [
-    {
-        "BACKEND": "django.template.backends.django.DjangoTemplates",
-        "DIRS": [
-            BASE_DIR / "templates",
-        ],
-        "OPTIONS": {
-            "builtins": [
-                "django_bird.templatetags.django_bird",
-            ],
-        },
-    }
-]
-```
-
-This configuration ensures that django-bird's templatetags are available globally.
 
-## `ENABLE_BIRD_ATTRS`
+### `ENABLE_BIRD_ATTRS`
 
 Controls whether components automatically receive data attributes related to django-bird in its `attrs` template context variable. Defaults to `True`.
 

src/django_bird/apps.py

@@ -15,14 +15,12 @@ class DjangoBirdAppConfig(AppConfig):
 
     @override
     def ready(self):
-        from django_bird.conf import app_settings
         from django_bird.plugins import pm
         from django_bird.staticfiles import asset_types
 
         for pre_ready in pm.hook.pre_ready():
             pre_ready()
 
-        app_settings.autoconfigure()
         pm.hook.register_asset_types(register_type=asset_types.register_type)
 
         for ready in pm.hook.ready():

src/django_bird/conf.py

@@ -1,111 +1,32 @@
 from __future__ import annotations
 
-import warnings
-from contextlib import suppress
 from dataclasses import dataclass
 from dataclasses import field
 from pathlib import Path
-from typing import Any
-from typing import final
 
-import django.template
 from django.conf import settings
 
-from django_bird import hookimpl
-
 from ._typing import override
 from .utils import unique_ordered
 
 DJANGO_BIRD_SETTINGS_NAME = "DJANGO_BIRD"
 
+DJANGO_BIRD_BUILTINS = "django_bird.templatetags.django_bird"
+DJANGO_BIRD_FINDER = "django_bird.staticfiles.BirdAssetFinder"
+
 
 @dataclass
 class AppSettings:
     COMPONENT_DIRS: list[Path | str] = field(default_factory=list)
-    ENABLE_AUTO_CONFIG: bool = True
     ENABLE_BIRD_ATTRS: bool = True
-    _configurator: AutoConfigurator = field(init=False)
-
-    def __post_init__(self):
-        self._configurator = AutoConfigurator(self)
 
     @override
     def __getattribute__(self, __name: str) -> object:
         user_settings = getattr(settings, DJANGO_BIRD_SETTINGS_NAME, {})
         return user_settings.get(__name, super().__getattribute__(__name))
 
-    def autoconfigure(self) -> None:
-        if not self.ENABLE_AUTO_CONFIG:
-            return
-
-        warnings.warn(
-            "Autoconfiguration of django-bird is deprecated and has been moved to the "
-            "django-bird-autoconf plugin. Please install the new plugin from PyPI in your "
-            "project if you wish to keep this behavior, as this will be removed from the "
-            "core library in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self._configurator.autoconfigure()
-
     def get_component_directory_names(self):
         return unique_ordered([*self.COMPONENT_DIRS, "bird"])
 
 
-@hookimpl
-def ready():
-    app_settings.autoconfigure()
-
-
-DJANGO_BIRD_BUILTINS = "django_bird.templatetags.django_bird"
-DJANGO_BIRD_FINDER = "django_bird.staticfiles.BirdAssetFinder"
-
-
-@final
-class AutoConfigurator:
-    def __init__(self, app_settings: AppSettings) -> None:
-        self.app_settings = app_settings
-        self._configured = False
-
-    def autoconfigure(self) -> None:
-        self.configure_templates()
-        self.configure_staticfiles()
-        self._configured = True
-
-    def configure_templates(self) -> None:
-        template_config = None
-
-        for config in settings.TEMPLATES:
-            engine_name = config.get("NAME") or config["BACKEND"].split(".")[-2]
-            if engine_name == "django":
-                template_config = config
-                break
-
-        if template_config is None:
-            return
-
-        options = template_config.setdefault("OPTIONS", {})
-
-        self.configure_builtins(options)
-
-        # Force re-evaluation of settings.TEMPLATES because EngineHandler caches it.
-        with suppress(AttributeError):  # pragma: no cover
-            del django.template.engines.templates
-            django.template.engines._engines = {}  # type:ignore[attr-defined] # pyright: ignore[reportAttributeAccessIssue]
-
-    def configure_builtins(self, options: dict[str, Any]) -> None:
-        builtins = options.setdefault("builtins", [])
-
-        builtins_already_configured = DJANGO_BIRD_BUILTINS in builtins
-
-        if not builtins_already_configured:
-            builtins.append(DJANGO_BIRD_BUILTINS)
-
-    def configure_staticfiles(self) -> None:
-        finders_already_configured = DJANGO_BIRD_FINDER in settings.STATICFILES_FINDERS
-
-        if not finders_already_configured:
-            settings.STATICFILES_FINDERS.append(DJANGO_BIRD_FINDER)
-
-
 app_settings = AppSettings()