Docs readability enhancements (#189)

- Change docs verbiage on several sections
- Recolor the "outdated docs" banner
- Add Google Analytics to the docs

Author: Archmonger

LICENSE

@@ -0,0 +1,9 @@
+## The MIT License (MIT)
+
+#### Copyright (c) Reactive Python and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LICENSE.md

@@ -2,12 +2,12 @@
 
 Due to Django's ORM design, database queries must be deferred using hooks. Otherwise, you will see a `#!python SynchronousOnlyOperation` exception.
 
-These `#!python SynchronousOnlyOperation` exceptions may be resolved in a future version of Django containing an asynchronous ORM. However, it is best practice to always perform ORM calls in the background via hooks.
+These `#!python SynchronousOnlyOperation` exceptions may be removed in a future version of Django. However, it is best practice to always perform IO operations (such as ORM queries) via hooks to prevent performance issues.
 
 <!--orm-excp-end-->
 
 <!--orm-fetch-start-->
 
-By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the default `#!python QueryOptions.postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components.
+By default, automatic recursive fetching of `#!python ManyToMany` or `#!python ForeignKey` fields is enabled within the `django_query_postprocessor`. This is needed to prevent `#!python SynchronousOnlyOperation` exceptions when accessing these fields within your ReactPy components.
 
 <!--orm-fetch-end-->

docs/includes/orm.md

@@ -0,0 +1,32 @@
+from reactpy import component, html
+from reactpy_django.hooks import use_mutation
+from reactpy_django.types import MutationOptions
+
+
+def execute_thread_safe_mutation():
+    """This is an example mutation function that does some thread-safe operation."""
+    pass
+
+
+@component
+def my_component():
+    item_mutation = use_mutation(
+        MutationOptions(thread_sensitive=False),
+        execute_thread_safe_mutation,
+    )
+
+    def submit_event(event):
+        if event["key"] == "Enter":
+            item_mutation.execute(text=event["target"]["value"])
+
+    if item_mutation.loading or item_mutation.error:
+        mutation_status = html.h2("Doing something...")
+    elif item_mutation.error:
+        mutation_status = html.h2("Error!")
+    else:
+        mutation_status = html.h2("Done.")
+
+    return html.div(
+        html.input({"type": "text", "onKeyDown": submit_event}),
+        mutation_status,
+    )

docs/python/use-mutation-thread-sensitive.py

@@ -3,8 +3,8 @@
 from reactpy_django.hooks import use_mutation
 
 
-def add_item(text: str):
-    TodoItem(text=text).save()
+async def add_item(text: str):
+    await TodoItem(text=text).asave()
 
 
 @component

docs/python/use-mutation.py

@@ -1,10 +1,11 @@
+from channels.db import database_sync_to_async
 from example.models import TodoItem
 from reactpy import component, html
 from reactpy_django.hooks import use_query
 
 
-def get_items():
-    return TodoItem.objects.all()
+async def get_items():
+    return await database_sync_to_async(TodoItem.objects.all)()
 
 
 @component

docs/python/use-query-async.py

@@ -0,0 +1,8 @@
+---
+hide:
+    - toc
+---
+
+---
+
+{% include "../../../LICENSE.md" %}

docs/python/use-query.py

@@ -0,0 +1,15 @@
+body[data-md-color-scheme="slate"] {
+	--md-banner-bg-color: #4d4121;
+	--md-banner-font-color: #fff;
+}
+
+body[data-md-color-scheme="default"] {
+	--md-banner-bg-color: #ff9;
+	--md-banner-font-color: #000;
+}
+
+.md-banner--warning {
+	background-color: var(--md-banner-bg-color);
+	color: var(--md-banner-font-color);
+	text-align: center;
+}

docs/src/about/license.md

@@ -27,3 +27,7 @@
 .legal-footer-right {
 	float: right;
 }
+
+.md-copyright__highlight div {
+	display: inline;
+}

docs/src/assets/css/banner.css

@@ -37,3 +37,4 @@ frontends
 misconfiguration
 misconfigurations
 backhaul
+sublicense

docs/src/assets/css/footer.css

@@ -177,7 +177,7 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering.
 
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
-    | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A |
+    | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on Django's `#!jinja {% static %}` template tag. | N/A |
     | `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `#!python None` |
 
     <font size="4">**Returns**</font>
@@ -186,10 +186,6 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering.
     | --- | --- |
     | `#!python Component` | A ReactPy component. |
 
-??? question "Should I put `#!python django_css` at the top of my HTML?"
-
-    Yes, if the stylesheet contains styling for your component.
-
 ??? question "Can I load static CSS using `#!python html.link` instead?"
 
     While you can load stylesheets with `#!python html.link`, keep in mind that loading this way **does not** ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause unintended visual behavior, so use this at your own discretion.
@@ -204,22 +200,26 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering.
 
     `#!python django_css` can only be used with local static files.
 
-    For external CSS, substitute `#!python django_css` with `#!python html.link`.
+    For external CSS, you should use `#!python html.link`.
 
     ```python
     {% include "../../python/django-css-external-link.py" %}
     ```
 
 ??? question "Why not load my CSS in `#!html <head>`?"
 
-    Traditionally, stylesheets are loaded in your `#!html <head>` using the `#!jinja {% load static %}` template tag.
+    Traditionally, stylesheets are loaded in your `#!html <head>` using Django's `#!jinja {% static %}` template tag.
 
-    To help improve webpage load times, you can use the `#!python django_css` component to defer loading your stylesheet until it is needed.
+    However, to help improve webpage load times you can use this `#!python django_css` component to defer loading your stylesheet until it is needed.
 
 ## Django JS
 
 Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within [Django's static files](https://docs.djangoproject.com/en/dev/howto/static-files/).
 
+!!! warning "Pitfall"
+
+    Be mindful of load order! If your JavaScript relies on the component existing on the page, you must place `django_js` at the **bottom** of your component.
+
 === "components.py"
 
     ```python
@@ -232,7 +232,7 @@ Allows you to defer loading JavaScript until a component begins rendering. This
 
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
-    | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A |
+    | `#!python static_path` | `#!python str` | The path to the static file. This path is identical to what you would use on Django's `#!jinja {% static %}` template tag. | N/A |
     | `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings | `#!python None` |
 
     <font size="4">**Returns**</font>
@@ -241,10 +241,6 @@ Allows you to defer loading JavaScript until a component begins rendering. This
     | --- | --- |
     | `#!python Component` | A ReactPy component. |
 
-??? question "Should I put `#!python django_js` at the bottom of my HTML?"
-
-    Yes, if your scripts are reliant on the contents of the component.
-
 ??? question "Can I load static JavaScript using `#!python html.script` instead?"
 
     While you can load JavaScript with `#!python html.script`, keep in mind that loading this way **does not** ensure load order. Thus, your JavaScript will likely be loaded at an arbitrary time after your component is displayed.
@@ -259,14 +255,14 @@ Allows you to defer loading JavaScript until a component begins rendering. This
 
     `#!python django_js` can only be used with local static files.
 
-    For external JavaScript, substitute `#!python django_js` with `#!python html.script`.
+    For external JavaScript, you should use `#!python html.script`.
 
     ```python
     {% include "../../python/django-js-remote-script.py" %}
     ```
 
 ??? question "Why not load my JS in `#!html <head>`?"
 
-    Traditionally, JavaScript is loaded in your `#!html <head>` using the `#!jinja {% load static %}` template tag.
+    Traditionally, JavaScript is loaded in your `#!html <head>` using Django's `#!jinja {% static %}` template tag.
 
-    To help improve webpage load times, you can use the `#!python django_js` component to defer loading your JavaScript until it is needed.
+    However, to help improve webpage load times you can use this `#!python django_js` component to defer loading your JavaScript until it is needed.

docs/src/dictionary.txt

@@ -10,7 +10,7 @@ Decorator functions can be used within your `components.py` to help simplify dev
 
 ## Auth Required
 
-You can limit access to a component to users with a specific `#!python auth_attribute` by using this decorator (with or without parentheses).
+You can limit component access to users with a specific `#!python auth_attribute` by using this decorator (with or without parentheses).
 
 By default, this decorator checks if the user is logged in and not deactivated (`#!python is_active`).