Docs version control and new theme (#176)

- Version controlled docs
   - Every time something is committed to `main`, it will update the `develop` docs.
   - Every time a version is released, it will push a new version number to the docs.
- Use our new ReactPy docs theme, which is an even better imitation of ReactJS docs 
- Fix `GITHUB_ACTIONS` env type conversion

Author: Archmonger

Diff for: .github/workflows/publish-develop-docs.yml

@@ -0,0 +1,18 @@
+name: Publish Develop Docs
+on:
+    push:
+        branches:
+            - main
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v3
+              with:
+                  fetch-depth: 0
+            - uses: actions/setup-python@v4
+              with:
+                  python-version: 3.x
+            - run: pip install -r requirements/build-docs.txt
+            - name: Publish Develop Docs
+              run: mike deploy --push develop

Diff for: .github/workflows/publish-docs.yml

@@ -0,0 +1,19 @@
+name: Publish Release Docs
+
+on:
+    release:
+        types: [published]
+
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v3
+              with:
+                  fetch-depth: 0
+            - uses: actions/setup-python@v4
+              with:
+                  python-version: 3.x
+            - run: pip install -r requirements/build-docs.txt
+            - name: Publish ${{ github.event.release.name }} Docs
+              run: mike deploy --push --update-aliases ${{ github.event.release.name }} latest

Diff for: .github/workflows/publish-release-docs.yml

@@ -34,6 +34,10 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
+### Added
+
+-   [ReactPy-Django docs](https://reactive-python.github.io/reactpy-django/) are now version controlled via [mike](https://github.com/jimporter/mike)!
+
 ### Changed
 
 -   Bumped the minimum ReactPy version to `1.0.2`.

Diff for: CHANGELOG.md

@@ -23,6 +23,8 @@
 <!--badge-end-->
 <!--intro-start-->
 
+[ReactPy-Django](https://github.com/reactive-python/reactpy-django) is used to add used to add [ReactPy](https://reactpy.dev/) support to an existing **Django project**.
+
 [ReactPy](https://reactpy.dev/) is a library for building user interfaces in Python without Javascript. ReactPy interfaces are made from components that look and behave similar to those found in [ReactJS](https://reactjs.org/). Designed with simplicity in mind, ReactPy can be used by those without web development experience while also being powerful enough to grow with your ambitions.
 
 <table align="center">
@@ -77,11 +79,12 @@ def hello_world(recipient: str):
 
 <!--html-header-start-->
 
-In your **Django app**'s HTML template, you can now embed your ReactPy 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.
-
-Additionally, you can pass in `args` and `kwargs` 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.
+In your **Django app**'s HTML template, you can now embed your ReactPy component using the `component` template tag. Within this tag, you will need to type in the dotted path to the component.
 
 <!--html-header-end-->
+
+Additionally, you can pass in `args` and `kwargs` into your component function. After reading the code below, pay attention to how the function definition for `hello_world` (_from the previous example_) accepts a `recipient` argument.
+
 <!--html-code-start-->
 
 ```jinja

Diff for: README.md

@@ -11,3 +11,10 @@
 </div>
 {% endif %}
 {% endblock %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}

Diff for: docs/overrides/main.html

@@ -3,8 +3,12 @@ hide:
     - toc
 ---
 
-!!! summary "Attribution"
+<p class="intro" markdown>
 
-        {% include-markdown "../../../CHANGELOG.md" start="<!--attr-start-->" end="<!--attr-end-->" %}
+{% include-markdown "../../../CHANGELOG.md" start="<!--attr-start-->" end="<!--attr-end-->" %}
+
+</p>
+
+---
 
 {% include-markdown "../../../CHANGELOG.md" start="<!--changelog-start-->" %}

Diff for: docs/src/changelog/index.md

@@ -1,12 +1,18 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
     You will need to set up a Python environment to develop ReactPy-Django.
 
-??? tip "Looking to contribute features that are not Django specific?"
+</p>
 
-    Everything within the `reactpy-django` repository must be specific to Django integration. Check out the [ReactPy Core documentation](https://reactpy.dev/docs/about/contributor-guide.html) to contribute general features such as: components, hooks, events, and more.
+!!! note
+
+    Looking to contribute features that are not Django specific?
+
+    Everything within the `reactpy-django` repository must be specific to Django integration. Check out the [ReactPy Core documentation](https://reactpy.dev/docs/about/contributor-guide.html) to contribute general features such as components, hooks, and events.
+
+---
 
 ## Modifying Code
 

Diff for: docs/src/contribute/code.md

@@ -1,8 +1,12 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    You will need to set up a Python environment to preview docs changes.
+You will need to set up a Python environment to create, test, and preview docs changes.
+
+</p>
+
+---
 
 ## Modifying Docs
 

Diff for: docs/src/contribute/docs.md

@@ -1,8 +1,12 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    You will need to set up a Python environment to run out test suite.
+You will need to set up a Python environment to run the ReactPy-Django test suite.
+
+</p>
+
+---
 
 ## Running Tests
 
@@ -29,17 +33,26 @@ By running the command below you can run the full test suite:
 nox -s test
 ```
 
-Or, if you want to run the tests in the foreground:
+Or, if you want to run the tests in the background:
 
 ```bash linenums="0"
-nox -s test -- --headed
+nox -s test -- --headless
 ```
 
-## Only Django Tests
+## Django Tests
 
-Alternatively, if you want to only run Django related tests, you can use the following command:
+If you want to only run our Django tests in your current environment, you can use the following command:
 
 ```bash linenums="0"
 cd tests
 python manage.py test
 ```
+
+## Django Test Webserver
+
+If you want to manually run the Django test application, you can use the following command:
+
+```bash linenums="0"
+cd tests
+python manage.py runserver
+```

Diff for: docs/src/contribute/running-tests.md

@@ -1,8 +1,12 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    Prefabricated components can be used within your `components.py` to help simplify development.
+We supply some pre-designed that components can be used to help simplify development.
+
+</p>
+
+---
 
 ## View To Component
 
@@ -29,7 +33,7 @@ Convert any Django view into a ReactPy component by using this decorator. Compat
 
     | Type | Description |
     | --- | --- |
-    | `_ViewComponentConstructor` | A function that takes `request, *args, key, **kwargs` and returns an ReactPy component. All parameters are directly provided to your view, besides `key` which is used by ReactPy. |
+    | `_ViewComponentConstructor` | A function that takes `request, *args, key, **kwargs` and returns a ReactPy component. All parameters are directly provided to your view, besides `key` which is used by ReactPy. |
 
 ??? Warning "Potential information exposure when using `compatibility = True`"
 
@@ -180,7 +184,7 @@ Allows you to defer loading a CSS stylesheet until a component begins rendering.
 
     | Type | Description |
     | --- | --- |
-    | `Component` | An ReactPy component. |
+    | `Component` | A ReactPy component. |
 
 ??? question "Should I put `django_css` at the top of my HTML?"
 
@@ -235,7 +239,7 @@ Allows you to defer loading JavaScript until a component begins rendering. This
 
     | Type | Description |
     | --- | --- |
-    | `Component` | An ReactPy component. |
+    | `Component` | A ReactPy component. |
 
 ??? question "Should I put `django_js` at the bottom of my HTML?"
 

Diff for: docs/src/features/components.md

@@ -1,8 +1,12 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    Decorator utilities can be used within your `components.py` to help simplify development.
+Decorator functions can be used within your `components.py` to help simplify development.
+
+</p>
+
+---
 
 ## Auth Required
 
@@ -31,7 +35,7 @@ This decorator is commonly used to selectively render a component only if a user
 
     | Type | Description |
     | --- | --- |
-    | `Component` | An ReactPy component. |
+    | `Component` | A ReactPy component. |
     | `VdomDict` | An `reactpy.html` snippet. |
     | `None` | No component render. |
 

Diff for: docs/src/features/decorators.md

@@ -1,14 +1,18 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    Prefabricated hooks can be used within your `components.py` to help simplify development.
+Prefabricated hooks can be used within your `components.py` to help simplify development.
 
-??? tip "Looking for standard React hooks?"
+</p>
 
-    The `reactpy-django` package only contains django specific hooks. Standard hooks can be found within [`reactive-python/reactpy`](https://github.com/reactive-python/reactpy). Since `reactpy` is installed alongside `reactpy-django`, you can import them at any time.
+!!! note
 
-    Check out the [ReactPy Core docs](https://reactpy.dev/docs/reference/hooks-api.html#basic-hooks) to see what hooks are available!
+    Looking for standard React hooks?
+
+    This package only contains Django specific hooks. Standard hooks can be found within [`reactive-python/reactpy`](https://reactpy.dev/docs/reference/hooks-api.html#basic-hooks).
+
+---
 
 ## Use Query
 

Diff for: docs/src/features/hooks.md

@@ -1,8 +1,18 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    Your **Django project's** `settings.py` can modify the behavior of ReactPy.
+Your **Django project's** `settings.py` can modify the behavior of ReactPy.
+
+</p>
+
+!!! note
+
+    The default configuration of ReactPy is suitable for the vast majority of use cases.
+
+    You should only consider changing settings when the necessity arises.
+
+---
 
 ## Primary Configuration
 
@@ -13,18 +23,12 @@ These are ReactPy-Django's default settings values. You can modify these values
 | Setting | Default Value | Example Value(s) | Description |
 | --- | --- | --- | --- |
 | `REACTPY_CACHE` | `#!python "default"` | `#!python "my-reactpy-cache"` | Cache used to store ReactPy web modules. ReactPy benefits from a fast, well indexed cache.<br/>We recommend installing [`redis`](https://redis.io/) or [`python-diskcache`](https://grantjenks.com/docs/diskcache/tutorial.html#djangocache). |
-| `REACTPY_DATABASE` | `#!python "default"` | `#!python "my-reactpy-database"` | Database ReactPy uses to store session data. ReactPy requires a multiprocessing-safe and thread-safe database.<br/>If configuring `REACTPY_DATABASE`, it is mandatory to also configure `DATABASE_ROUTERS` like such:<br/>`#!python DATABASE_ROUTERS = ["reactpy_django.database.Router", ...]` |
+| `REACTPY_DATABASE` | `#!python "default"` | `#!python "my-reactpy-database"` | Database used to store ReactPy session data. ReactPy requires a multiprocessing-safe and thread-safe database.<br/>If configuring `REACTPY_DATABASE`, it is mandatory to use our database router like such:<br/>`#!python DATABASE_ROUTERS = ["reactpy_django.database.Router", ...]` |
 | `REACTPY_RECONNECT_MAX` | `#!python 259200` | `#!python 96000`, `#!python 60`, `#!python 0` | Maximum seconds between reconnection attempts before giving up.<br/>Use `#!python 0` to prevent reconnection. |
 | `REACTPY_URL_PREFIX` | `#!python "reactpy/"` | `#!python "rp/"`, `#!python "render/reactpy/"` | The prefix to be used for all ReactPy websocket and HTTP URLs. |
 | `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` | `#!python "reactpy_django.utils.django_query_postprocessor"` | `#!python "example_project.my_query_postprocessor"` | Dotted path to the default `reactpy_django.hooks.use_query` postprocessor function. |
 | `REACTPY_AUTH_BACKEND` | `#!python "django.contrib.auth.backends.ModelBackend"` | `#!python "example_project.auth.MyModelBackend"` | Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if:<br/> 1. You are using `AuthMiddlewareStack` and...<br/> 2. You are using Django's `AUTHENTICATION_BACKENDS` setting and...<br/> 3. Your Django user model does not define a `backend` attribute. |
 | `REACTPY_BACKHAUL_THREAD` | `#!python False` | `#!python True` | Whether to render ReactPy components in a dedicated thread. This allows the webserver to process web traffic while during ReactPy rendering.<br/>Vastly improves throughput with web servers such as `hypercorn` and `uvicorn`. |
-| `REACTPY_DEFAULT_HOSTS` | `#!python None` | `#!python ["localhost:8000", "localhost:8001", "localhost:8002/subdir" ]` | Default host(s) to use for ReactPy components. ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.<br/>You can use the `host` argument in your [template tag](../features/template-tag.md#component) to override this default. |
+| `REACTPY_DEFAULT_HOSTS` | `#!python None` | `#!python ["localhost:8000", "localhost:8001", "localhost:8002/subdir" ]` | The default host(s) that can render your ReactPy components. ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing.<br/>You can use the `host` argument in your [template tag](../features/template-tag.md#component) as a manual override. |
 
 <!--config-details-end-->
-
-??? question "Do I need to modify my settings?"
-
-    The default configuration of ReactPy is suitable for the majority of use cases.
-
-    You should only consider changing settings when the necessity arises.

Diff for: docs/src/features/settings.md

@@ -1,8 +1,12 @@
 ## Overview
 
-!!! summary "Overview"
+<p class="intro" markdown>
 
-    Template tags can be used within your Django templates such as `my-template.html` to import ReactPy features.
+Django template tags can be used within your HTML templates to provide ReactPy features.
+
+</p>
+
+---
 
 ## Component
 
@@ -20,14 +24,16 @@ The `component` template tag can be used to insert any number of ReactPy compone
     | --- | --- | --- | --- |
     | `dotted_path` | `str` | The dotted path to the component to render. | N/A |
     | `*args` | `Any` | The positional arguments to provide to the component. | N/A |
+    | `class` | `str | None` | The HTML class to apply to the top-level component div. | `None` |
+    | `key` | `str | None` | Force the component's root node to use a [specific key value](https://reactpy.dev/docs/guides/creating-interfaces/rendering-data/index.html#organizing-items-with-keys). Using `key` within a template tag is effectively useless. | `None` |
     | `host` | `str | None` | The host to use for the ReactPy connections. If set to `None`, the host will be automatically configured.<br/>Example values include: `localhost:8000`, `example.com`, `example.com/subdir` | `None` |
     | `**kwargs` | `Any` | The keyword arguments to provide to the component. | N/A |
 
     <font size="4">**Returns**</font>
 
     | Type | Description |
     | --- | --- |
-    | `Component` | An ReactPy component. |
+    | `Component` | A ReactPy component. |
 
 <!--context-start-->
 
@@ -56,24 +62,6 @@ The `component` template tag can be used to insert any number of ReactPy compone
         ```
 
 <!--context-end-->
-<!--reserved-arg-start-->
-
-??? info "Reserved keyword arguments: `class` and `key`"
-
-    For this template tag, there are two reserved keyword arguments: `class` and `key`
-
-    -   `class` allows you to apply a HTML class to the top-level component div. This is useful for styling purposes.
-    -   `key` allows you to force the component's root node to use a [specific key value](https://reactpy.dev/docs/guides/creating-interfaces/rendering-data/index.html#organizing-items-with-keys). Using `key` within a template tag is effectively useless.
-
-    === "my-template.html"
-
-        ```jinja
-        ...
-        {% component "example.components.my_component" class="my-html-class" key=123 %}
-        ...
-        ```
-
-<!--reserved-sarg-end-->
 
 ??? question "Can I render components on a different server (distributed computing)?"