Skip to content

Commit 9f0fa65

Browse files
ArchmongerArchmonger
authored
Docs revision (#85)
* use snake_case component names * add settings.py to exclusive features * change light/dark mode icons * create docs tests * configure test workflows properly * rename workflow/jobs * remove alternative title on hooks page * format all docs
1 parent e182a7e commit 9f0fa65

File tree

16 files changed

+111
-76
lines changed

16 files changed

+111
-76
lines changed

‎.github/workflows/test-docs.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
schedule:
11+
- cron: "0 0 * * *"
12+
13+
jobs:
14+
docs:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v2
18+
- uses: actions/setup-python@v2
19+
with:
20+
python-version: 3.x
21+
- run: pip install -r requirements/build-docs.txt
22+
- run: mkdocs build --verbose

‎.github/workflows/test.yml renamed to ‎.github/workflows/test-src.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ on:
1111
- cron: "0 0 * * *"
1212

1313
jobs:
14-
test-python-versions:
14+
source:
1515
runs-on: ubuntu-latest
1616
strategy:
1717
matrix:

‎README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Any Python web framework with Websockets can support IDOM. See below for what fr
2525

2626
<!--py-header-start-->
2727

28-
You'll need a file to define your [IDOM](https://github.com/idom-team/idom) components. We recommend creating a `components.py` file within your chosen **Django app** to start out. Within this file, we will create a simple `HelloWorld` component.
28+
You'll need a file to define your [IDOM](https://github.com/idom-team/idom) components. We recommend creating a `components.py` file within your chosen **Django app** to start out. Within this file, we will create a simple `hello_world` component.
2929

3030
<!--py-header-end-->
3131
<!--py-code-start-->
@@ -34,7 +34,7 @@ You'll need a file to define your [IDOM](https://github.com/idom-team/idom) comp
3434
from idom import component, html
3535

3636
@component
37-
def HelloWorld(recipient: str):
37+
def hello_world(recipient: str):
3838
return html.h1(f"Hello {recipient}!")
3939
```
4040

@@ -46,7 +46,7 @@ def HelloWorld(recipient: str):
4646

4747
In your **Django app**'s HTML template, you can now embed your IDOM component using the `component` template tag. Within this tag, you will need to type in your dotted path to the component function as the first argument.
4848

49-
Additonally, you can pass in keyword arguments into your component function. For example, after reading the code below, pay attention to how the function definition for `HelloWorld` (_in the previous example_) accepts a `recipient` argument.
49+
Additonally, you can pass in keyword arguments into your component function. For example, after reading the code below, pay attention to how the function definition for `hello_world` (_in the previous example_) accepts a `recipient` argument.
5050

5151
<!--html-header-end-->
5252
<!--html-code-start-->
@@ -56,7 +56,7 @@ Additonally, you can pass in keyword arguments into your component function. For
5656
<!DOCTYPE html>
5757
<html>
5858
<body>
59-
{% component "example_project.my_app.components.HelloWorld" recipient="World" %}
59+
{% component "example_project.my_app.components.hello_world" recipient="World" %}
6060
</body>
6161
</html>
6262
```

‎docs/features/components.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ from idom import component, html
77
from django_idom.components import django_css
88

99
@component
10-
def MyComponent():
10+
def my_component():
1111
return html.div(
1212
django_css("css/buttons.css"),
1313
html.button("My Button!"),
@@ -29,7 +29,7 @@ def MyComponent():
2929
from django.templatetags.static import static
3030

3131
@component
32-
def MyComponent():
32+
def my_component():
3333
return html.div(
3434
html.link({"rel": "stylesheet", "href": static("css/buttons.css")}),
3535
html.button("My Button!"),
@@ -46,7 +46,7 @@ def MyComponent():
4646
from idom import component, html
4747

4848
@component
49-
def MyComponent():
49+
def my_component():
5050
return html.div(
5151
html.link({"rel": "stylesheet", "href": "https://example.com/external-styles.css"}),
5252
html.button("My Button!"),
@@ -68,7 +68,7 @@ from idom import component, html
6868
from django_idom.components import django_js
6969

7070
@component
71-
def MyComponent():
71+
def my_component():
7272
return html.div(
7373
html.button("My Button!"),
7474
django_js("js/scripts.js"),
@@ -90,7 +90,7 @@ def MyComponent():
9090
from django.templatetags.static import static
9191

9292
@component
93-
def MyComponent():
93+
def my_component():
9494
return html.div(
9595
html.script({"src": static("js/scripts.js")}),
9696
html.button("My Button!"),
@@ -107,7 +107,7 @@ def MyComponent():
107107
from idom import component, html
108108

109109
@component
110-
def MyComponent():
110+
def my_component():
111111
return html.div(
112112
html.script({"src": static("https://example.com/external-scripts.js")}),
113113
html.button("My Button!"),

‎docs/features/hooks.md

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
# Django Hooks
2-
31
???+ tip "Looking for more hooks?"
42

53
Check out the [IDOM Core docs](https://idom-docs.herokuapp.com/docs/reference/hooks-api.html?highlight=hooks) on hooks!
@@ -13,13 +11,11 @@ from idom import component, html
1311
from django_idom.hooks import use_websocket
1412

1513
@component
16-
def MyComponent():
14+
def my_component():
1715
my_websocket = use_websocket()
1816
return html.div(my_websocket)
1917
```
2018

21-
22-
2319
## Use Scope
2420

2521
This is a shortcut that returns the Websocket's `scope`.
@@ -29,17 +25,16 @@ from idom import component, html
2925
from django_idom.hooks import use_scope
3026

3127
@component
32-
def MyComponent():
28+
def my_component():
3329
my_scope = use_scope()
3430
return html.div(my_scope)
3531
```
3632

37-
3833
## Use Location
3934

4035
??? info "This hook's behavior will be changed in a future update"
4136

42-
This hook will be updated to return the browser's current URL. This will come in alongside our built-in [Single Page Application (SPA) support](https://github.com/idom-team/idom/issues/569).
37+
This hook will be updated to return the browser's current URL. This change will come in alongside [IDOM URL routing support](https://github.com/idom-team/idom/issues/569).
4338

4439
This is a shortcut that returns the Websocket's `path`.
4540

@@ -48,7 +43,7 @@ from idom import component, html
4843
from django_idom.hooks import use_location
4944

5045
@component
51-
def MyComponent():
46+
def my_component():
5247
my_location = use_location()
5348
return html.div(my_location)
5449
```

‎docs/features/settings.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Django IDOM uses your **Django project's** `settings.py` file to modify some behaviors of IDOM.
2+
3+
Here are the configurable variables that are available.
4+
5+
<!--settings-start-->
6+
7+
```python title="settings.py"
8+
# If "idom" cache is not configured, then we'll use "default" instead
9+
CACHES = {
10+
"idom": {"BACKEND": ...},
11+
}
12+
13+
# Maximum seconds between two reconnection attempts that would cause the client give up.
14+
# 0 will disable reconnection.
15+
IDOM_WS_MAX_RECONNECT_TIMEOUT = 604800
16+
17+
# The URL for IDOM to serve websockets
18+
IDOM_WEBSOCKET_URL = "idom/"
19+
```
20+
21+
<!--settings-end-->
22+
23+
??? question "Do I need to modify my settings?"
24+
25+
The default configuration of IDOM is adequate for the majority of use cases.
26+
27+
You should only consider changing settings when the necessity arises.

‎docs/features/templatetag.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,16 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
1414

1515
```python title="views.py"
1616
def example_view():
17-
context_vars = {"DontDoThis": "example_project.my_app.components.HelloWorld"}
17+
context_vars = {"dont_do_this": "example_project.my_app.components.hello_world"}
1818
return render(request, "my-template.html", context_vars)
1919
```
2020

2121
```jinja title="my-template.html"
2222
<!-- This is bad -->
23-
{% component DontDoThis recipient="World" %}
23+
{% component dont_do_this recipient="World" %}
2424

2525
<!-- This is good -->
26-
{% component "example_project.my_app.components.HelloWorld" recipient="World" %}
26+
{% component "example_project.my_app.components.hello_world" recipient="World" %}
2727
```
2828

2929
<!--context-end-->
@@ -38,7 +38,7 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
3838

3939
```jinja title="my-template.html"
4040
...
41-
{% component "example.components.MyComponent" class="my-html-class" key=123 %}
41+
{% component "example.components.my_component" class="my-html-class" key=123 %}
4242
...
4343
```
4444

@@ -54,15 +54,17 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
5454
<!DOCTYPE html>
5555
<html>
5656
<body>
57-
{% component "example_project.my_app.components.HelloWorld" recipient="World" %}
58-
{% component "example_project.my_app_2.components.ClassComponent" class="bold small-font" %}
59-
<div>{% component "example_project.my_app_3.components.SimpleComponent" %}</div>
57+
{% component "example_project.my_app.components.hello_world" recipient="World" %}
58+
{% component "example_project.my_app_2.components.class_component" class="bold small-font" %}
59+
<div>{% component "example_project.my_app_3.components.simple_component" %}</div>
6060
</body>
6161
</html>
6262
```
6363

6464
But keep in mind, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one central component within your `#!html <body>` tag.
6565

66+
Additionally, the components in the example above will not be able to interact with each other, except through database queries.
67+
6668
<!--multiple-components-end-->
6769
<!--kwargs-start-->
6870

‎docs/installation/index.md

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -43,19 +43,7 @@ INSTALLED_APPS = [
4343

4444
Below are a handful of values you can change within `settings.py` to modify the behavior of IDOM.
4545

46-
```python title="settings.py"
47-
# If "idom" cache is not configured, then we'll use "default" instead
48-
CACHES = {
49-
"idom": {"BACKEND": ...},
50-
}
51-
52-
# Maximum seconds between two reconnection attempts that would cause the client give up.
53-
# 0 will disable reconnection.
54-
IDOM_WS_MAX_RECONNECT_TIMEOUT = 604800
55-
56-
# The URL for IDOM to serve websockets
57-
IDOM_WEBSOCKET_URL = "idom/"
58-
```
46+
{% include-markdown "../features/settings.md" start="<!--settings-start-->" end="<!--settings-end-->" %}
5947

6048
---
6149

‎mkdocs.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ nav:
1212
- Components: features/components.md
1313
- Hooks: features/hooks.md
1414
- Template Tag: features/templatetag.md
15+
- Settings: features/settings.md
1516
- Contribute:
1617
- Code: contribute/django-idom.md
1718
- Docs: contribute/docs.md
@@ -24,14 +25,14 @@ theme:
2425
- media: "(prefers-color-scheme: dark)"
2526
scheme: slate
2627
toggle:
27-
icon: material/toggle-switch
28+
icon: material/white-balance-sunny
2829
name: Switch to light mode
2930
primary: deep-orange
3031
accent: orange
3132
- media: "(prefers-color-scheme: light)"
3233
scheme: default
3334
toggle:
34-
icon: material/toggle-switch-off-outline
35+
icon: material/weather-night
3536
name: Switch to dark mode
3637
primary: black
3738
features:

‎src/django_idom/templatetags/idom.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def component(_component_id_, **kwargs):
2626
<!DOCTYPE html>
2727
<html>
2828
<body>
29-
{% component "example_project.my_app.components.HelloWorld" recipient="World" %}
29+
{% component "example_project.my_app.components.hello_world" recipient="World" %}
3030
</body>
3131
</html>
3232
"""

0 commit comments

Comments
 (0)