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;
+}