diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0892a7a..bd67b07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ We adhere to Django's Code of Conduct in all interactions and expect all contrib ## Setup -The following setup steps assume you are using a Unix-like operating system, such as Linux or macOS, and that you have a [supported](README.md#requirements) version of Python installed. If you are using Windows, you will need to adjust the commands accordingly. If you do not have Python installed, you can visit [python.org](https://www.python.org/) for instructions on how to install it for your operating system. +The following setup steps assume you are using a Unix-like operating system, such as Linux or macOS, and that you have a [supported](https://django-bird.readthedocs.io/#requirements) version of Python installed. If you are using Windows, you will need to adjust the commands accordingly. If you do not have Python installed, you can visit [python.org](https://www.python.org/) for instructions on how to install it for your operating system. 1. Fork the repository and clone it locally. 2. Create a virtual environment and activate it. You can use whatever tool you prefer for this. Below is an example using the Python standard library's `venv` module: diff --git a/README.md b/README.md index a07c11f..db8c344 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # django-bird [![PyPI](https://img.shields.io/pypi/v/django-bird)](https://pypi.org/project/django-bird/) @@ -9,9 +10,11 @@ High-flying components for perfectionists with deadlines. + > [!CAUTION] -> This is an experimental, pre-alpha attempt at a different approach to defining components in Django templates. It is not suitable for production use yet. +> This is an experimental, alpha attempt at a different approach to defining components in Django templates. It is not suitable for production use yet. + ## Requirements - Python 3.10, 3.11, 3.12, 3.13 @@ -40,42 +43,11 @@ High-flying components for perfectionists with deadlines. ] ``` -3. django-bird requires two settings in your `settings.TEMPLATES` to be configured to work properly: +3. django-bird will automatically configure the necessary settings in your project. No further action is required for most use cases. - - `django_bird.templatetags.django_bird` in the `builtins` - - `django_bird.loader.BirdLoader` in the innermost list of `loaders`, before `django.template.loaders.filesystem.Loader` and `django.template.loaders.app_directories.Loader` + 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. - By default, these should be configured for you automatically. If you would like to disable this behavior and set this up yourself, you will need to set `DJANGO_BIRD["ENABLE_AUTO_CONFIG"] = False`. - - ```python - # settings.py - DJANGO_BIRD = { - "ENABLE_AUTO_CONFIG": False, - } - - TEMPLATES = [ - { - "BACKEND": "django.template.backends.django.DjangoTemplates", - "DIRS": [...], - "OPTIONS": { - "builtins": [ - "django_bird.templatetags.django_bird", - ], - "loaders": [ - ( - "django.template.loaders.cached.Loader", - [ - "django_bird.loader.BirdLoader", - "django.template.loaders.filesystem.Loader", - "django.template.loaders.app_directories.Loader", - ], - ), - ], - }, - } - ] - - ``` + For detailed instructions, please refer to the [Manual Setup](https://django-bird.readthedocs.io/configuration.html#manual-setup) section within the Configuration documentation. ## Getting Started @@ -121,7 +93,8 @@ django-bird automatically recognizes components in the bird directory, so no man ``` -You now a button component that can be easily reused across your Django project. +You now have a button component that can be easily reused across your Django project. + ## Documentation @@ -131,15 +104,19 @@ django-bird includes features for creating flexible components, including: - Named slots for organizing content within components - Subcomponents for building complex component structures -For a full overview of the features and configuration options, please refer to the [documentation](https://bird.readthedocs.io/). +For a full overview of the features and configuration options, please refer to the [documentation](https://bird.readthedocs.io). + +## Motivation and Roadmap + +### Roadmap -## Roadmap +#### Static Asset Collection -### Custom HTML Tag +#### Component Islands -### Component Islands +#### Custom HTML Tag -### Scoped CSS Styles +#### Scoped CSS Styles ## License diff --git a/docs/conf.py b/docs/conf.py index 5aa95bf..521e1ae 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,8 +29,8 @@ # -- Project information ----------------------------------------------------- -project = "bird" -copyright = "2023, Josh Thomas" +project = "django-bird" +copyright = "2024, Josh Thomas" author = "Josh Thomas" @@ -60,6 +60,9 @@ myst_heading_anchors = 3 # -- Options for autodoc2 ----------------------------------------------------- +autodoc2_docstring_parser_regexes = [ + (r".*", "myst"), +] autodoc2_packages = [f"../src/{project.replace('-', '_')}"] autodoc2_render_plugin = "myst" @@ -89,7 +92,7 @@ "footer_icons": [ { "name": "GitHub", - "url": "https://github.com/joshuadavidthomas/bird", + "url": "https://github.com/joshuadavidthomas/django-bird", "html": """ diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..4938894 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,112 @@ +# Configuration + +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: + +```{code-block} python +:caption: settings.py + +from pathlib import Path + +DJANGO_BIRD = { + "COMPONENT_DIRS": list[Path | str] = [], + "ENABLE_AUTO_CONFIG": bool = True, +} +``` + +## `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 + +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. + +You can configure django-bird to look in all these locations: + +```{code-block} python +:caption: settings.py + +from pathlib import Path + +BASE_DIR = Path(__file__).resolve(strict=True).parent + +DJANGO_BIRD = { + "COMPONENT_DIRS": [ + "components", + Path("third_party_library/components"), + BASE_DIR / "alternate_templates" / "bird", + ] +} +``` + +In this configuration: + +- `"components"` is a string path relative to your project's templates directory. +- `Path("third_party_library/components")` uses the `Path` object for the third-party library's components. +- `BASE_DIR / "alternate_templates" / "bird"` constructs a path using Django's `BASE_DIR` setting, similar to how other Django settings can be configured. + +With this setup, django-bird will search for components in the following order: + +1. `components` +2. `third_party_library/components` +3. `alternate_templates/bird` +4. The default `bird` directory + +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. +2. Include django-bird's loader in your template loaders, ensuring it comes before Django's default filesystem and app directories loaders. + +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", + ], + "loaders": [ + ( + "django.template.loaders.cached.Loader", + [ + "django_bird.loader.BirdLoader", + "django.template.loaders.filesystem.Loader", + "django.template.loaders.app_directories.Loader", + ], + ), + ], + }, + } +] +``` + +This configuration ensures that django-bird's templatetags are available globally and that its loader is used to compile bird component templates before the standard Django loaders. diff --git a/docs/index.md b/docs/index.md index 85d05b3..0baf96e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,17 @@ ```{include} ../README.md +:start-after: '' +:end-before: '' +``` + +```{include} ../README.md +:start-after: '' +:end-before: '' +``` +```{toctree} +:hidden: +:maxdepth: 3 +configuration ``` ```{toctree} @@ -7,12 +19,12 @@ :maxdepth: 3 :caption: API Reference -apidocs/bird/bird.rst +apidocs/django_bird/django_bird.rst ``` ```{toctree} :hidden: -:maxdepth: 3 +:maxdepth: 2 :caption: Development development/contributing.md