migrate docs to mkdocs

Author: amirreza8002

.readthedocs.yaml

@@ -1,16 +1,15 @@
-version: "2"
+version: 2
 
 build:
   os: "ubuntu-lts-latest"
   tools:
-    python: "3.12"
+    python: "3.13"
 
   jobs:
     pre_build:
-      - pip install .
-      - pip install sphinx-pdj-theme
-sphinx:
-  configuration: docs/source/conf.py
+      - pip install mkdocs-material mkdocs-awesome-nav
+mkdocs:
+  configuration: mkdocs.yml
 
 formats:
   - pdf

CHANGES.rst CHANGES.md

@@ -0,0 +1,13 @@
+sort:
+  sections: first
+
+nav:
+  - installation.md
+
+  - configure
+  - async
+  - commands
+
+  - migration_from_django_redis.md
+  - customize.md
+  - changes.md

docs/.nav.yml

@@ -0,0 +1,5 @@
+nav:
+  - configurations.md
+  - advanced_configurations.md
+  - async_commands.md
+  - access_to_pool.md

docs/Makefile

@@ -0,0 +1,14 @@
+# Access the connection pool
+
+you can get the connection pool using this code:
+
+```python
+from django_valkey.async_cache import get_valkey_connection
+
+async def get_connection():
+    r = await get_valkey_connection("default")  # use the name defined in ``CACHES`` settings
+    connection_pool = r.connection_pool
+    print(f"created connections so far: {connection_pool._created_connections}")
+```
+
+this will verify how many connections the pool has opened.

docs/async/.nav.yml

@@ -0,0 +1,112 @@
+# Advanced Async Configuration
+
+most of the subject discussed in [Advanced configuration](../configure/advanced_configurations.md) apply to async mode as well, just don't use a sync client :)
+
+also all the compressor details we talked about in [Compressor support](../configure/compressors.md) work as is in async mode
+
+**Important**: the async clients are not compatible with django's cache middleware.
+if you need those middlewares, consider using a sync client or implement a new middleware
+
+## Clients
+
+We have three async client, `AsyncDefaultClient`, available in `django_valkey.async_cache.client.default`, `AsyncHerdClient` available in `django_valkey.async_cache.client.herd` and `AsyncSentinelClient` at `django_valkey.async_cache.client.sentinel`.
+the default client can also be used with sentinels, as we'll discuss later.
+
+note that all clients are imported and available at `django_valkey.async_cache.client`
+
+### Default client
+
+the `AsyncDefaultClient` is configured by default by `AsyncValkeyCache`, so if you have configured that as your backend you are all set, but if you want to be explicit or use the client with a different backend you can write it like this:
+
+```python
+CACHES = {
+    "async": {
+        "BACKEND": "path.to.backend",
+        "LOCATION": [
+            "valkey://user:[email protected]:6379",
+        ]
+        "OPTIONS": {
+            "CLIENT_CLASS": "django_valkey.async_cache.client.AsyncDefaultClient",
+        }
+    }
+}
+```
+
+or you can replace the client with your own like that.
+
+### Sentinel Client
+
+to support sentinels, django_valkey comes with a client and a connection factory, technically you don't need the connection factory, but it provides you with some nice features.
+a dedicated page on sentinel client has been written in [Sentinel configuration](../configure/sentinel_configurations.md), tho that is for the sync version, the principle is the same.
+
+the connection factory is at `django_valkey.async_cache.pool.AsyncSentinelConnectionFactory`.
+
+to configure the async sentinel client you can write your settings like this:
+
+```python
+SENTINELS = [
+    ("127.0.0.1", 26379),  # a list of (host name, port) tuples.
+]
+
+CACHES = {
+    "default": {
+        "BACKEND": "django_valkey.async_cache.cache.AsyncValkeyCache",
+        "LOCATION": "valkey://service_name/db",
+        "OPTIONS": {
+            "CLIENT_CLASS": "django_valkey.client.SentinelClient",
+            "SENTINELS": SENTINELS,
+
+            # optional
+            "SENTINEL_KWARGS": {}
+        }
+    }
+}
+```
+
+*note*: the sentinel client uses the sentinel connection factory by default, you can change it by setting `DJANGO_VALKEY_CONNECTION_FACTORY` in your django settings or `CONNECTION_FACTORY` in your `CACHES` OPTIONS.
+
+### Herd client
+
+the herd client needs to be configured, but it's as simple as this:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "django_valkey.async_cache.cache.AsyncValkeyCache",
+        "LOCATION": ["valkey://127.0.0.1:6379"],
+        "OPTIONS": {
+            "CLIENT_CLASS": "django_valkey.async_cache.client.AsyncHerdClient",
+        }
+    }
+}
+```        
+
+## Connection Factory
+
+django_valkey's async library comes with two connection factories, `AsyncConnectionFactory` for general uses and `AsyncSentinelConnectionFactory` for sentinel uses.
+
+the default connection factory is `AsyncConnectionFactory`, so if you are using a sentinel server you should configure your caches like this:
+
+```python
+CACHES = {
+    "async": {
+        # ...
+        "OPTIONS": {
+            "CONNECTION_FACTORY": "django_valkey.async_cache.pool.AsyncSentinelConnectionFactory"
+        }
+    }
+}
+
+CACHE_HERD_TIMEOUT = 20  # if not set, it's default to 60
+```
+
+or set it as the global connection factory like this:
+
+```python
+DJANGO_VALKEY_CONNECTION_FACTORY = "django_valkey.async_cache.client.default.AsyncDefaultClient"
+```    
+
+note that `"CONNECTION_FACTORY"` overrides `DJANGO_VALKEY_CONNECTION_FACTORY` for the specified server.
+
+if you want to use another factory you can use the same code with the path to your class.
+

docs/async/access_to_pool.md

@@ -0,0 +1,28 @@
+# Valkey native commands
+
+you can directly work with valkey using django's cache object.
+
+most subject discussed in [valkey commands](../commands/valkey_native_commands.md) also applies here.
+
+```pycon
+>>> from django.core.cache import cache
+
+>>> await cache.aget("foo")
+```
+
+the method names are the same as the sync ones discussed in [valkey commands](../commands/valkey_native_commands.md), and the API is almost the same.
+
+the only difference is that the async backend returns a coroutine or async generator depending on the method, and you should `await` it or iterate over it.
+
+```python
+import contextlib
+from django.core.cache import cache
+
+async with contextlib.aclosing(cache.aiter_keys("foo*")) as keys:
+    async for k in keys:
+        print(k)
+```
+
+another thing to notice is that the method names are the same as the sync ones: `await get()` or `get()`.
+but if you want to be explicit the same methods are also available with a `a` prepended to them: `await aget()`.
+this goes for all public methods of the async client.

docs/async/advanced_configurations.md

@@ -0,0 +1,45 @@
+# Configure The Async Client
+
+**Warning**: as of django 5.2, async support for cache backends is flaky, if you decide to use the async backends do so with caution.
+
+**Important**: the async client is not compatible with django's cache middlewares.
+if you need the middlewares, consider using the sync client or implement a new middleware.
+
+there are two async clients available, a normal client and a herd client.
+
+## Default client
+
+to setup the async client you can configure your settings file to look like this:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "django_valkey.async_cache.cache.AsyncValkeyCache",
+        "LOCATION": "valkey://127.0.0.1:6379",
+        "OPTIONS": {...},
+    },
+}
+```
+
+take a look at [Configure the database URL](../configure/advanced_configurations.md#configure-the-database-url) to see other ways to write the URL.
+And that's it, the backend defaults to use AsyncDefaultClient as client interface, AsyncConnectionFactory as connection factory and valkey-py's async client.
+
+you can, of course configure it to use any other class, or pass in extras args and kwargs, the same way that was discussed at [Advanced Configurations](../configure/advanced_configurations.md).
+
+## Herd client
+
+to set up herd client configure your settings like this:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "django_valkey.async_cache.caches.AsyncValkeyCache",
+        "LOCATION": "valkey://127.0.0.1:6379",
+        "OPTIONS": {
+            "CLIENT_CLASS": "django_valkey.async_cache.client.AsyncHerdClient",
+        },
+    },
+}
+```
+
+for a more specified guide look at [Advanced Async Configuration](advanced_configurations.md).

docs/async/async_commands.md

@@ -0,0 +1,2 @@
+# Change Log
+--8<-- "./CHANGES.md"

docs/async/configurations.md

@@ -0,0 +1,3 @@
+nav:
+  - connection_pool_commands.md
+  - valkey_native_commands.md

docs/changes.md

@@ -0,0 +1,13 @@
+# Access the connection pool
+
+you can get the connection pool using this code:
+
+```python
+from django_valkey import get_valkey_connection
+
+r = get_valkey_connection("default")  # use the name defined in ``CACHES`` settings
+connection_pool = r.connection_pool
+print(f"created connections so far: {connection_pool._created_connections}")
+```
+
+this will verify how many connections the pool has opened.