reactive-python · rmorshea · Jul 3, 2022 · Jul 2, 2022 · Jul 2, 2022 · Jul 2, 2022
@@ -0,0 +1,22 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * *"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements/build-docs.txt
+      - run: mkdocs build --verbose
@@ -11,7 +11,7 @@ on:
     - cron: "0 0 * * *"
 
 jobs:
-  test-python-versions:
+  source:
     runs-on: ubuntu-latest
     strategy:
       matrix:

@@ -25,7 +25,7 @@ Any Python web framework with Websockets can support IDOM. See below for what fr
 
 <!--py-header-start-->
 
-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.
+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.
 
 <!--py-header-end-->
 <!--py-code-start-->
@@ -34,7 +34,7 @@ You'll need a file to define your [IDOM](https://github.com/idom-team/idom) comp
 from idom import component, html
 
 @component
-def HelloWorld(recipient: str):
+def hello_world(recipient: str):
     return html.h1(f"Hello {recipient}!")
 ```
 
@@ -46,7 +46,7 @@ def HelloWorld(recipient: str):
 
 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.
 
-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.
+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.
 
 <!--html-header-end-->
 <!--html-code-start-->
@@ -56,7 +56,7 @@ Additonally, you can pass in keyword arguments into your component function. For
 <!DOCTYPE html>
 <html>
   <body>
-    {% component "example_project.my_app.components.HelloWorld" recipient="World" %}
+    {% component "example_project.my_app.components.hello_world" recipient="World" %}
   </body>
 </html>
 ```

@@ -7,7 +7,7 @@ from idom import component, html
 from django_idom.components import django_css
 
 @component
-def MyComponent():
+def my_component():
     return html.div(
         django_css("css/buttons.css"),
         html.button("My Button!"),
@@ -29,7 +29,7 @@ def MyComponent():
     from django.templatetags.static import static
 
     @component
-    def MyComponent():
+    def my_component():
         return html.div(
             html.link({"rel": "stylesheet", "href": static("css/buttons.css")}),
             html.button("My Button!"),
@@ -46,7 +46,7 @@ def MyComponent():
     from idom import component, html
 
     @component
-    def MyComponent():
+    def my_component():
         return html.div(
             html.link({"rel": "stylesheet", "href": "https://example.com/external-styles.css"}),
             html.button("My Button!"),
@@ -68,7 +68,7 @@ from idom import component, html
 from django_idom.components import django_js
 
 @component
-def MyComponent():
+def my_component():
     return html.div(
         html.button("My Button!"),
         django_js("js/scripts.js"),
@@ -90,7 +90,7 @@ def MyComponent():
     from django.templatetags.static import static
 
     @component
-    def MyComponent():
+    def my_component():
         return html.div(
             html.script({"src": static("js/scripts.js")}),
             html.button("My Button!"),
@@ -107,7 +107,7 @@ def MyComponent():
     from idom import component, html
 
     @component
-    def MyComponent():
+    def my_component():
         return html.div(
             html.script({"src": static("https://example.com/external-scripts.js")}),
             html.button("My Button!"),

@@ -1,5 +1,3 @@
-# Django Hooks
-
 ???+ tip "Looking for more hooks?"
 
     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
 from django_idom.hooks import use_websocket
 
 @component
-def MyComponent():
+def my_component():
     my_websocket = use_websocket()
     return html.div(my_websocket)
 ```
 
-
-
 ## Use Scope
 
 This is a shortcut that returns the Websocket's `scope`.
@@ -29,17 +25,16 @@ from idom import component, html
 from django_idom.hooks import use_scope
 
 @component
-def MyComponent():
+def my_component():
     my_scope = use_scope()
     return html.div(my_scope)
 ```
 
-
 ## Use Location
 
 ??? info "This hook's behavior will be changed in a future update"
 
-    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).
+    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).
 
 This is a shortcut that returns the Websocket's `path`.
 
@@ -48,7 +43,7 @@ from idom import component, html
 from django_idom.hooks import use_location
 
 @component
-def MyComponent():
+def my_component():
     my_location = use_location()
     return html.div(my_location)
 ```
@@ -0,0 +1,27 @@
+Django IDOM uses your **Django project's** `settings.py` file to modify some behaviors of IDOM.
+
+Here are the configurable variables that are available.
+
+<!--settings-start-->
+
+```python title="settings.py"
+# If "idom" cache is not configured, then we'll use "default" instead
+CACHES = {
+"idom": {"BACKEND": ...},
+}
+
+# Maximum seconds between two reconnection attempts that would cause the client give up.
+# 0 will disable reconnection.
+IDOM_WS_MAX_RECONNECT_TIMEOUT = 604800
+
+# The URL for IDOM to serve websockets
+IDOM_WEBSOCKET_URL = "idom/"
+```
+
+<!--settings-end-->
+
+??? question "Do I need to modify my settings?"
+
+    The default configuration of IDOM is adequate for the majority of use cases.
+
+    You should only consider changing settings when the necessity arises.
@@ -14,16 +14,16 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
 
     ```python title="views.py"
     def example_view():
-        context_vars = {"DontDoThis": "example_project.my_app.components.HelloWorld"}
+        context_vars = {"dont_do_this": "example_project.my_app.components.hello_world"}
         return render(request, "my-template.html", context_vars)
     ```
 
     ```jinja title="my-template.html"
     <!-- This is bad -->
-    {% component DontDoThis recipient="World" %}
+    {% component dont_do_this recipient="World" %}
 
     <!-- This is good -->
-    {% component "example_project.my_app.components.HelloWorld" recipient="World" %}
+    {% component "example_project.my_app.components.hello_world" recipient="World" %}
     ```
 
 <!--context-end-->
@@ -38,7 +38,7 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
 
     ```jinja title="my-template.html"
     ...
-    {% component "example.components.MyComponent" class="my-html-class" key=123 %}
+    {% component "example.components.my_component" class="my-html-class" key=123 %}
     ...
     ```
 
@@ -54,15 +54,17 @@ Integrated within Django IDOM, we bundle a template tag. Within this tag, you ca
     <!DOCTYPE html>
     <html>
         <body>
-        {% component "example_project.my_app.components.HelloWorld" recipient="World" %}
-        {% component "example_project.my_app_2.components.ClassComponent" class="bold small-font" %}
-        <div>{% component "example_project.my_app_3.components.SimpleComponent" %}</div>
+        {% component "example_project.my_app.components.hello_world" recipient="World" %}
+        {% component "example_project.my_app_2.components.class_component" class="bold small-font" %}
+        <div>{% component "example_project.my_app_3.components.simple_component" %}</div>
         </body>
     </html>
     ```
 
     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.
 
+    Additionally, the components in the example above will not be able to interact with each other, except through database queries.
+
 <!--multiple-components-end-->
 <!--kwargs-start-->
 

@@ -43,19 +43,7 @@ INSTALLED_APPS = [
 
     Below are a handful of values you can change within `settings.py` to modify the behavior of IDOM.
 
-    ```python title="settings.py"
-    # If "idom" cache is not configured, then we'll use "default" instead
-    CACHES = {
-    "idom": {"BACKEND": ...},
-    }
-
-    # Maximum seconds between two reconnection attempts that would cause the client give up.
-    # 0 will disable reconnection.
-    IDOM_WS_MAX_RECONNECT_TIMEOUT = 604800
-
-    # The URL for IDOM to serve websockets
-    IDOM_WEBSOCKET_URL = "idom/"
-    ```
+    {% include-markdown "../features/settings.md" start="<!--settings-start-->" end="<!--settings-end-->" %}
 
 ---
 

@@ -12,6 +12,7 @@ nav:
           - Components: features/components.md
           - Hooks: features/hooks.md
           - Template Tag: features/templatetag.md
+          - Settings: features/settings.md
     - Contribute:
           - Code: contribute/django-idom.md
           - Docs: contribute/docs.md
@@ -24,14 +25,14 @@ theme:
         - media: "(prefers-color-scheme: dark)"
           scheme: slate
           toggle:
-              icon: material/toggle-switch
+              icon: material/white-balance-sunny
               name: Switch to light mode
           primary: deep-orange
           accent: orange
         - media: "(prefers-color-scheme: light)"
           scheme: default
           toggle:
-              icon: material/toggle-switch-off-outline
+              icon: material/weather-night
               name: Switch to dark mode
           primary: black
     features:

@@ -26,7 +26,7 @@ def component(_component_id_, **kwargs):
         <!DOCTYPE html>
         <html>
         <body>
-            {% component "example_project.my_app.components.HelloWorld" recipient="World" %}
+            {% component "example_project.my_app.components.hello_world" recipient="World" %}
         </body>
         </html>
     """
-Original file line number
+Diff line change
@@ Expand Up / @@ -26,7 +26,7 @@ def component(_component_id_, **kwargs): @@
             <!DOCTYPE html>
             <html>
             <body>
-                {% component "example_project.my_app.components.HelloWorld" recipient="World" %}
+                {% component "example_project.my_app.components.hello_world" recipient="World" %}
             </body>
             </html>
         """
@@ Expand Down @@