improve docs clarity

Author: Archmonger

docs/src/reference/components.md

@@ -14,6 +14,8 @@ This allows you to embedded any number of client-side PyScript components within
 
 {% include-markdown "../reference/template-tag.md" start="<!--pyscript-def-start-->" end="<!--pyscript-def-end-->" %}
 
+{% include-markdown "../reference/template-tag.md" start="<!--pyscript-raw-text-start-->" end="<!--pyscript-raw-text-end-->" %}
+
 === "components.py"
 
     ```python

docs/src/reference/decorators.md

@@ -12,7 +12,7 @@ Decorator functions can be used within your `components.py` to help simplify dev
 
 You can limit component access to users that pass a test function by using this decorator.
 
-This decorator is inspired by Django's [`user_passes_test`](http://docs.djangoproject.com/en/dev/topics/auth/default/#django.contrib.auth.decorators.user_passes_test) decorator, but works with ReactPy components.
+This decorator is inspired by Django's [`user_passes_test`](http://docs.djangoproject.com/en/dev/topics/auth/default/#django.contrib.auth.decorators.user_passes_test) decorator, but this one works with ReactPy components.
 
 === "components.py"
 

docs/src/reference/hooks.md

@@ -400,7 +400,7 @@ This is often used to create chat systems, synchronize data between components,
 
     In these cases, you can use the `#!python use_channel_layer` hook to receive a signal within your component, and then use the `#!python get_channel_layer().send(...)` to send the signal.
 
-    In the example below, the sender will send a signal every time `#!python ExampleModel` is saved. Then, when the receiver component gets this signal, it explicitly calls `#!python set_message(...)` to trigger a re-render.
+    In the example below, the sender will signal every time `#!python ExampleModel` is saved. Then, when the receiver gets this signal, it explicitly calls `#!python set_message(...)` to trigger a re-render.
 
     === "signals.py"
 
@@ -522,7 +522,7 @@ You can expect this hook to provide strings such as `http://example.com`.
 
 Shortcut that returns the root component's `#!python id` from the WebSocket or HTTP connection.
 
-The root ID is currently a randomly generated `#!python uuid4` (unique across all root component).
+The root ID is a randomly generated `#!python uuid4`. It is noteable to mention that it is persistent across the current connection. The `uuid` is reset when the page is refreshed.
 
 This is useful when used in combination with [`#!python use_channel_layer`](#use-channel-layer) to send messages to a specific component instance, and/or retain a backlog of messages in case that component is disconnected via `#!python use_channel_layer( ... , group_discard=False)`.
 

docs/src/reference/html.md

@@ -10,11 +10,11 @@ We supply some pre-generated that HTML nodes can be used to help simplify develo
 
 ## PyScript
 
-Primitive HTML tag that is leveraged by [`reactpy_django.components.pyscript_component`](./components.md#pyscript-component).
+PyScript code block. The text content of this tag are executed within the PyScript interpreter. This can be used as an alternative to the `#!python reactpy.html.script`.
 
-This can be used as an alternative to the `#!python reactpy.html.script` tag to execute JavaScript and run client-side Python code.
+This is a primitive HTML tag that is leveraged by [`reactpy_django.components.pyscript_component`](./components.md#pyscript-component).
 
-Additionally, this tag functions identically to any other tag contained within `#!python reactpy.html`, and can be used in the same way.
+The `pyscript` tag functions identically to HTML tags contained within `#!python reactpy.html`.
 
 === "components.py"
 

docs/src/reference/template-tag.md

@@ -10,7 +10,7 @@ Django template tags can be used within your HTML templates to provide ReactPy f
 
 ## Component
 
-This template tag can be used to insert any number of ReactPy components onto your page.
+This template tag can be used to insert any number of **server-side** ReactPy components onto your page.
 
 Each component loaded via this template tag will receive a dedicated WebSocket connection to the server.
 
@@ -159,16 +159,19 @@ This template tag can be used to insert any number of **client-side** ReactPy co
 
 By default, the only dependencies available are the Python standard library, `pyscript`, `pyodide`, `reactpy` core.
 
-Your PyScript component file requires a `#!python def root()` component to function as the entry point.
+The entire file path provided is loaded directly into the browser, and must have a `#!python def root()` component to act as the entry point.
 
 <!--pyscript-def-end-->
+<!--pyscript-raw-text-start-->
 
 !!! warning "Pitfall"
 
     Your provided Python file is loaded directly into the client (web browser) **as raw text**, and ran using a PyScript interpreter. Be cautious about what you include in your Python file.
 
     As a result of running client-side, Python packages within your local environment (such as those installed via `pip install ...`)  are **not accessible** within PyScript components.
 
+<!--pyscript-raw-text-end-->
+
 === "my_template.html"
 
     ```jinja

docs/src/reference/utils.md

@@ -14,7 +14,7 @@ Utility functions provide various miscellaneous functionality for advanced use c
 
 ## Register Iframe
 
-This function is used register a view as an `#!python iframe` with ReactPy.
+This function is used register a Django view as a ReactPy `#!python iframe`.
 
 It is mandatory to use this function alongside [`view_to_iframe`](../reference/components.md#view-to-iframe).