mirror of
https://github.com/django-components/django-components.git
synced 2025-09-26 15:39:08 +00:00
chore: working docs
This commit is contained in:
Gabriel Dugny
Emil Stenström
parent
295ea95d1b
commit
95400944ec
22 changed files with 158 additions and 84 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -73,3 +73,4 @@ poetry.lock
|
|||
.DS_Store
|
||||
.python-version
|
||||
site
|
||||
docs/reference
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
8
docs/SUMMARY.md
Normal file
8
docs/SUMMARY.md
Normal file
|
|
@ -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/)
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1,47 @@
|
|||
--8<-- "README.md"
|
||||
# django-components
|
||||
|
||||
[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://EmilStenstrom.github.io/django-components/latest/license/) [](https://pypistats.org/packages/django-components) [](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
|
||||
<div class="calendar-component">Today's date is <span>2015-06-19</span></div>
|
||||
```
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
# License
|
||||
|
||||
```
|
||||
--8<-- "LICENSE"
|
||||
```
|
||||
|
|
|
|||
16
docs/user_guide/SUMMARY.md
Normal file
16
docs/user_guide/SUMMARY.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -127,6 +127,8 @@ This is fine too:
|
|||
|
||||
## Components as views
|
||||
|
||||
|
||||
<!-- md:version 0.34 -->
|
||||
_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.
|
||||
|
|
|
|||
|
|
@ -1 +1,5 @@
|
|||
[TOC]
|
||||
# Getting started
|
||||
|
||||
## Summary
|
||||
|
||||
--8<-- "docs/user_guide/SUMMARY.md:2"
|
||||
|
|
|
|||
|
|
@ -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,`*
|
||||
73
mkdocs.yml
73
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
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)])
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
"""Helper types for IDEs."""
|
||||
|
||||
import typing
|
||||
from typing import Any
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue