chore: working docs

.gitignore

@@ -73,3 +73,4 @@ poetry.lock
 .DS_Store
 .python-version
 site
+docs/reference

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.
 

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/)

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
 ```
 

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
+<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.

docs/license.md

@@ -1,5 +1,3 @@
 # License
 
-```
 --8<-- "LICENSE"
-```

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)

docs/user_guide/creating_using_components/using_slots.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.

docs/user_guide/index.md

@@ -1 +1,5 @@
-[TOC]
+# Getting started
+
+## Summary
+
+--8<-- "docs/user_guide/SUMMARY.md:2"

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,`*

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
+        - changelog.md
-        - CODE_OF_CONDUCT.md
+        - code_of_conduct.md
         - license.md
   - git-authors:
       enabled: !ENV [CI, false]
       exclude:
         - reference/*
-        - CHANGELOG.md
+        - changelog.md
-        - CODE_OF_CONDUCT.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:
-  #     minify_html: true
+      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

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]

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
+    # via
-pillow==10.2.0
+    #   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

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)])

src/django_components/types.py

@@ -1,3 +1,5 @@
+"""Helper types for IDEs."""
+
 import typing
 from typing import Any