diff --git a/.gitignore b/.gitignore index be28b494..389be594 100644 --- a/.gitignore +++ b/.gitignore @@ -73,3 +73,4 @@ poetry.lock .DS_Store .python-version site +docs/reference diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d276771a..cbe37513 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,10 +1,12 @@ # Release notes -🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of components to the new syntax automatically. +🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. + + `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of components to the new syntax automatically. This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases. -**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#components-as-views) for more details. +**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](user_guide/creating_using_components/using_slots.md#components-as-views) for more details. **Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..c370a8cd --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,8 @@ +* [Home](index.md) + * [Changelog](changelog.md) + * [Code of Conduct](code_of_conduct.md) + * [License](license.md) +* [Usage](user_guide/) +* [Developer Guide](dev_guide/index.md) +* Reference + * [API Reference](reference/) diff --git a/docs/dev_guide/index.md b/docs/dev_guide/index.md index 992a9218..724c83e5 100644 --- a/docs/dev_guide/index.md +++ b/docs/dev_guide/index.md @@ -30,13 +30,12 @@ pytest The library is also tested across many versions of Python and Django. To run tests that way: ```bash -pyenv install -s 3.7 pyenv install -s 3.8 pyenv install -s 3.9 pyenv install -s 3.10 pyenv install -s 3.11 pyenv install -s 3.12 -pyenv local 3.6 3.7 3.8 3.9 3.10 3.11 3.12 +pyenv local 3.8 3.9 3.10 3.11 3.12 tox -p ``` diff --git a/docs/index.md b/docs/index.md index 612c7a5e..06b1d899 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,47 @@ ---8<-- "README.md" +# django-components + +[![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://EmilStenstrom.github.io/django-components/latest/license/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/EmilStenstrom/django-components/tests.yml)](https://github.com/EmilStenstrom/django-components/actions/workflows/tests.yml) + +Create simple reusable template components in Django + +## Features + +- ✨ **Reusable components**: [Create components](user_guide/creating_using_components/create_first_component.md) that can be reused in different parts of your project, or even in different projects. +- 📁 **Single file components**: [Keep your Python, CSS, Javascript and HTML in one place](user_guide/creating_using_components/single_file_component.md) (if you wish) +- 🎰 **Slots**: Define [slots](user_guide/creating_using_components/using_slots.md) in your components to make them more flexible. +- 💻 **CLI**: A [command line interface](user_guide/commands.md) to help you create new components. +- 🚀 **Wide compatibility**: Works with [modern and LTS versions of Django](user_guide/installation/requirements_compatibility.md). +- **Load assets**: Automatically load the right CSS and Javascript files for your components, with [our middleware](user_guide/creating_using_components/middleware.md). + + +## Summary + +It lets you create "template components", that contains both the template, the Javascript and the CSS needed to generate the front end code you need for a modern app. Use components like this: + +```htmldjango +{% component "calendar" date="2015-06-19" %}{% endcomponent %} +``` + +And this is what gets rendered (plus the CSS and Javascript you've specified): + +```html +
Today's date is 2015-06-19
+``` + +Read our [user guide](user_guide/index.md) to set it up and learn about the details! + +## Compatibility + +`django-components` is compatible with modern and LTS versions of Django. + +Check out the [compatibility guide](user_guide/installation/requirements_compatibility.md) to see which versions are supported. + +## Community examples + +One of our goals with `django-components` is to make it easy to share components between projects. If you have a set of components that you think would be useful to others, please open a pull request to add them to the list below. + +- [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/). Try out the [live demo](https://dhc.iwanalabs.com/). + +## License + +`django-components` is licensed under the MIT license. See the [LICENSE](license.md) file for more details. diff --git a/docs/license.md b/docs/license.md index a873d2b5..0e8c6fca 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,5 +1,3 @@ # License -``` --8<-- "LICENSE" -``` diff --git a/docs/user_guide/SUMMARY.md b/docs/user_guide/SUMMARY.md new file mode 100644 index 00000000..abef6c02 --- /dev/null +++ b/docs/user_guide/SUMMARY.md @@ -0,0 +1,16 @@ +* [Getting Started](index.md) +* [Installation](installation/index.md) + * [Compatibility & Requirements](installation/requirements_compatibility.md) +* Creating & Using Components + * [Creating Your First Component](creating_using_components/create_first_component.md) + * [Using Components](creating_using_components/use_component.md) + * [Single File Components](creating_using_components/single_file_component.md) + * [Context Scope](creating_using_components/context_scope.md) + * [Using Slots](creating_using_components/using_slots.md) + * [Advanced Component Usage](creating_using_components/advanced.md) +* Integration with your Django project + * [Security](integration/security.md) + * [Middleware](integration/middleware.md) + * [Settings](integration/settings.md) + * [CLI Commands](integration/commands.md) + * [Logging and Debugging](integration/logging_debugging.md) diff --git a/docs/user_guide/creating_using_components/using_slots.md b/docs/user_guide/creating_using_components/using_slots.md index ba0d4be0..6962309c 100644 --- a/docs/user_guide/creating_using_components/using_slots.md +++ b/docs/user_guide/creating_using_components/using_slots.md @@ -127,6 +127,8 @@ This is fine too: ## Components as views + + _New in version 0.34_ Components can now be used as views. To do this, [`Component`][django_components.component.Component] subclasses Django's [`View`][] class. This means that you can use all of the [methods](https://docs.djangoproject.com/en/5.0/ref/class-based-views/base/#view) of `View` in your component. For example, you can override `get` and `post` to handle GET and POST requests, respectively. diff --git a/docs/user_guide/getting_started.md b/docs/user_guide/getting_started.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 260ad31a..55940d10 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -1 +1,5 @@ -[TOC] +# Getting started + +## Summary + +--8<-- "docs/user_guide/SUMMARY.md:2" diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation/index.md similarity index 79% rename from docs/user_guide/installation.md rename to docs/user_guide/installation/index.md index d1cf6434..68ff3284 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation/index.md @@ -2,9 +2,25 @@ Install the app into your environment: -> ```pip install django-components``` +=== "pip" -Then add the app into [`INSTALLED_APPS`][INSTALLED_APPS] in settings.py + ```bash + pip install django-components + ``` + +=== "poetry" + + ```bash + poetry add django-components + ``` + +=== "pdm" + + ```bash + pdm add django-components + ``` + +Then add the app into [`INSTALLED_APPS`][INSTALLED_APPS] in your settings module (e.g. `settings.py`) ```python INSTALLED_APPS = [ @@ -13,7 +29,7 @@ INSTALLED_APPS = [ ] ``` -Modify [`TEMPLATES`][TEMPLATES] section of settings.py as follows: +Modify [`TEMPLATES`][TEMPLATES] section of your settings module as follows: - *Remove `'APP_DIRS': True,`* diff --git a/docs/user_guide/requirements_compatibility.md b/docs/user_guide/installation/requirements_compatibility.md similarity index 100% rename from docs/user_guide/requirements_compatibility.md rename to docs/user_guide/installation/requirements_compatibility.md diff --git a/docs/user_guide/commands.md b/docs/user_guide/integration/commands.md similarity index 100% rename from docs/user_guide/commands.md rename to docs/user_guide/integration/commands.md diff --git a/docs/user_guide/logging_debugging.md b/docs/user_guide/integration/logging_debugging.md similarity index 100% rename from docs/user_guide/logging_debugging.md rename to docs/user_guide/integration/logging_debugging.md diff --git a/docs/user_guide/creating_using_components/middleware.md b/docs/user_guide/integration/middleware.md similarity index 100% rename from docs/user_guide/creating_using_components/middleware.md rename to docs/user_guide/integration/middleware.md diff --git a/docs/user_guide/security.md b/docs/user_guide/integration/security.md similarity index 100% rename from docs/user_guide/security.md rename to docs/user_guide/integration/security.md diff --git a/docs/user_guide/settings.md b/docs/user_guide/integration/settings.md similarity index 100% rename from docs/user_guide/settings.md rename to docs/user_guide/integration/settings.md diff --git a/mkdocs.yml b/mkdocs.yml index d0636da1..a8106b23 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,9 +19,10 @@ watch: - scripts validation: - omitted_files: warn + # We get warnings as we use literate-nav + omitted_files: ignore absolute_links: warn - unrecognized_links: warn + unrecognized_links: info theme: name: "material" @@ -76,39 +77,6 @@ extra: - icon: fontawesome/brands/python link: https://pypi.org/project/django-components/ -nav: - - Home: - - index.md - - Changelog: CHANGELOG.md - - Code of Conduct: CODE_OF_CONDUCT.md - - License: license.md - - Usage: #user_guide/ - - # - user_guide/index.md - - Installation: - - user_guide/installation.md - - user_guide/requirements_compatibility.md - - user_guide/getting_started.md - - user_guide/security.md - - Creating & Using Components: - - user_guide/creating_using_components/create_first_component.md - - user_guide/creating_using_components/use_component.md - - user_guide/creating_using_components/single_file_component.md - - user_guide/creating_using_components/context_scope.md - - user_guide/creating_using_components/using_slots.md - - user_guide/creating_using_components/middleware.md - - user_guide/creating_using_components/advanced.md - - user_guide/settings.md - - user_guide/commands.md - - user_guide/logging_debugging.md - - - - Development: - - dev_guide/index.md - - Reference: - - API: reference/ - - markdown_extensions: abbr: {} admonition: {} @@ -150,26 +118,27 @@ plugins: - gen-files: scripts: - scripts/gen_ref_nav.py - - literate-nav + - literate-nav: + nav_file: SUMMARY.md + tab_length: 2 - git-revision-date-localized: enabled: !ENV [CI, false] type: timeago exclude: - reference/* - - CHANGELOG.md - - CODE_OF_CONDUCT.md + - changelog.md + - code_of_conduct.md - license.md - git-authors: enabled: !ENV [CI, false] exclude: - reference/* - - CHANGELOG.md - - CODE_OF_CONDUCT.md + - changelog.md + - code_of_conduct.md - license.md - markdown-exec # - toc-md: - search - - section-index - social: enabled: !ENV [CI, false] - mike: @@ -177,8 +146,8 @@ plugins: version_selector: true - redirects: redirect_maps: - # - minify: - # minify_html: true + - minify: + minify_html: true - mkdocstrings: handlers: python: @@ -189,24 +158,6 @@ plugins: domains: [std, py] paths: [src] # search packages in the src folder options: - # docstring_options: - # ignore_init_summary: true - # docstring_section_style: list - # filters: ["!^_"] - # heading_level: 1 - # inherited_members: true - # merge_init_into_class: true - # preload_modules: [mkdocstrings] - # separate_signature: true - # show_root_heading: true - # show_root_full_path: false - # show_signature_annotations: true - # show_source: false - # show_symbol_type_heading: true - # show_symbol_type_toc: true - # signature_crossrefs: true - # summary: true - # unwrap_annotated: true docstring_options: ignore_init_summary: true docstring_section_style: list diff --git a/pyproject.toml b/pyproject.toml index 252d4d90..5f12ccbe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -122,11 +122,11 @@ lock-filename = "requirements-dev.txt" [tool.hatch.envs.docs] type = "pip-compile" lock-filename = "requirements-docs.txt" - +detached = false # Dependencies are fetched automatically from the mkdocs.yml file with hatch-mkdocs # We only add black for formatting code in the docs dependencies = [ - "black" + "black", ] [tool.hatch.env.collectors.mkdocs.docs] diff --git a/requirements-docs.txt b/requirements-docs.txt index 9f3c56f2..78edaba3 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -13,17 +13,23 @@ # - mkdocs-literate-nav # - mkdocs-material # - mkdocs-material[imaging] +# - mkdocs-minify-plugin # - mkdocs-redirects -# - mkdocs-section-index # - mkdocstrings # - mkdocstrings-python # - pymdown-extensions +# - black +# - django>=3.2 # +asgiref==3.8.1 + # via django babel==2.14.0 # via # mkdocs-git-revision-date-localized-plugin # mkdocs-material +black==24.3.0 + # via hatch.envs.docs bracex==2.4 # via wcmatch cairocffi==1.6.1 @@ -38,16 +44,21 @@ charset-normalizer==3.3.2 # via requests click==8.1.7 # via + # black # mkdocs # mkdocstrings colorama==0.4.6 # via # griffe # mkdocs-material +csscompressor==0.9.5 + # via mkdocs-minify-plugin cssselect2==0.7.0 # via cairosvg defusedxml==0.7.1 # via cairosvg +django==5.0.3 + # via hatch.envs.docs ghp-import==2.1.0 # via mkdocs gitdb==4.0.11 @@ -56,6 +67,8 @@ gitpython==3.1.43 # via mkdocs-git-revision-date-localized-plugin griffe==0.42.1 # via mkdocstrings-python +htmlmin2==0.1.13 + # via mkdocs-minify-plugin idna==3.6 # via requests importlib-metadata==7.1.0 @@ -68,6 +81,8 @@ jinja2==3.1.3 # mkdocs # mkdocs-material # mkdocstrings +jsmin==3.0.1 + # via mkdocs-minify-plugin markdown==3.5.2 # via # mdx-truly-sane-lists @@ -102,8 +117,8 @@ mkdocs==1.5.3 # mkdocs-include-markdown-plugin # mkdocs-literate-nav # mkdocs-material + # mkdocs-minify-plugin # mkdocs-redirects - # mkdocs-section-index # mkdocstrings mkdocs-autorefs==1.0.1 # via @@ -123,9 +138,9 @@ mkdocs-material==9.5.16 # via hatch.envs.docs mkdocs-material-extensions==1.3.1 # via mkdocs-material -mkdocs-redirects==1.2.1 +mkdocs-minify-plugin==0.8.0 # via hatch.envs.docs -mkdocs-section-index==0.3.8 +mkdocs-redirects==1.2.1 # via hatch.envs.docs mkdocstrings==0.24.1 # via @@ -133,18 +148,25 @@ mkdocstrings==0.24.1 # mkdocstrings-python mkdocstrings-python==1.9.0 # via hatch.envs.docs +mypy-extensions==1.0.0 + # via black packaging==24.0 - # via mkdocs + # via + # black + # mkdocs paginate==0.5.6 # via mkdocs-material pathspec==0.12.1 - # via mkdocs -pillow==10.2.0 + # via + # black + # mkdocs +pillow==10.3.0 # via # cairosvg # mkdocs-material platformdirs==4.2.0 # via + # black # mkdocs # mkdocstrings pycparser==2.22 @@ -171,7 +193,7 @@ pyyaml==6.0.1 # pyyaml-env-tag pyyaml-env-tag==0.1 # via mkdocs -regex==2023.12.25 +regex==2022.10.31 # via mkdocs-material requests==2.31.0 # via mkdocs-material @@ -179,6 +201,8 @@ six==1.16.0 # via python-dateutil smmap==5.0.1 # via gitdb +sqlparse==0.4.4 + # via django tinycss2==1.2.1 # via # cairosvg diff --git a/scripts/gen_ref_nav.py b/scripts/gen_ref_nav.py index a12fd186..ae73e99c 100644 --- a/scripts/gen_ref_nav.py +++ b/scripts/gen_ref_nav.py @@ -20,13 +20,18 @@ src = root / "src" for path in sorted(src.rglob("*.py")): module_path = path.relative_to(src).with_suffix("") - doc_path = path.relative_to(src).with_suffix(".md") + if module_path.parts[-1] == "__init__": + module_path = module_path.parent + doc_path = path.relative_to(src).with_suffix("") + if doc_path.parts[-1] == "__init__": + doc_path = doc_path.parent full_doc_path = Path("reference", doc_path) parts = tuple(module_path.parts) doc_path = doc_path / "index.md" full_doc_path = full_doc_path / "index.md" + nav_parts = [f"{mod_symbol} {part}" for part in parts] nav[tuple(nav_parts)] = doc_path.as_posix() if parts[-1] == "__init__": @@ -39,4 +44,4 @@ for path in sorted(src.rglob("*.py")): mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root)) with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: - nav_file.writelines(nav.build_literate_nav()) + nav_file.writelines([line.replace(" ", " ").removeprefix(" ") for line in nav.build_literate_nav(indentation=2)]) diff --git a/src/django_components/types.py b/src/django_components/types.py index 37394687..73f9db75 100644 --- a/src/django_components/types.py +++ b/src/django_components/types.py @@ -1,3 +1,5 @@ +"""Helper types for IDEs.""" + import typing from typing import Any