Docs update (#285)

Author: s3rius

docs/.vuepress/config.ts

@@ -1,6 +1,6 @@
 import { defineUserConfig } from "vuepress";
-import { searchProPlugin } from "vuepress-plugin-search-pro";
 import { hopeTheme } from "vuepress-theme-hope";
+import { viteBundler } from '@vuepress/bundler-vite'
 
 export default defineUserConfig({
   lang: "en-US",
@@ -16,6 +16,8 @@ export default defineUserConfig({
     ],
   ],
 
+  bundler: viteBundler(),
+
   theme: hopeTheme({
     hostname: "https://taskiq-python.github.io",
     logo: "/logo.svg",
@@ -28,7 +30,6 @@ export default defineUserConfig({
     sidebar: "structure",
 
     pure: true,
-    backToTop: false,
 
     plugins: {
       readingTime: false,
@@ -45,8 +46,10 @@ export default defineUserConfig({
         changefreq: "daily",
         sitemapFilename: "sitemap.xml",
       },
+      searchPro: {
+        indexContent: true,
+        autoSuggestions: false,
+      }
     },
-  }),
-
-  plugins: [searchProPlugin({ indexContent: true })],
+  })
 });

docs/available-components/schedule-sources.md

@@ -7,6 +7,23 @@ order: 4
 These objects are used to fetch current schedule for tasks.
 Currently we have only one schedule source.
 
+## RedisScheduleSource
+
+This source is capable of adding new schedules in runtime. It uses Redis as a storage for schedules.
+To use this source you need to install `taskiq-redids` package.
+
+```python
+from taskiq_redis import RedisScheduleSource
+
+from taskiq import TaskiqScheduler
+
+redis_source = RedisScheduleSource("redis://localhost:6379/0")
+scheduler = TaskiqScheduler(broker, sources=[redis_source])
+```
+
+For more information on how to use dynamic schedule sources read [Dynamic scheduling section](../guide/scheduling-tasks.md#dynamic-scheduling).
+
+
 ## LabelScheduleSource
 
 This source parses labels of tasks, and if it finds a `schedule` label, it considers this task as scheduled.

docs/contrib.md

@@ -4,17 +4,6 @@ order: 5
 
 # Contribution guide
 
-We love contributions. This guide is for all folks who want to make taskiq
-better together.
-
-We have several rules for contributors:
-* Please do not add malware.
-* Please make sure that your request solves problem.
-
-If you struggle with something or feel frustrating, you either create an issue, create a discussion on page or publish draft PR and ask your question in description.
-
-We have lots of tests in CI. But since runs from first-time contributors should be approved you better test locally, it just takes less time.
-
 We love contributions. This guide is for all folks who want to make taskiq better together.
 We have several rules for contributors:
 * Please do not add malware.

docs/examples/schedule/redis_schedule.py

@@ -0,0 +1,18 @@
+from taskiq_redis import ListQueueBroker, RedisScheduleSource
+
+from taskiq import TaskiqScheduler
+
+# Here's the broker that is going to execute tasks
+broker = ListQueueBroker("redis://localhost:6379/0")
+
+# Here's the source that is used to store scheduled tasks
+redis_source = RedisScheduleSource("redis://localhost:6379/0")
+
+# And here's the scheduler that is used to query scheduled sources
+scheduler = TaskiqScheduler(broker, sources=[redis_source])
+
+
+@broker.task
+async def my_task(arg1: int, arg2: str) -> None:
+    """Example task."""
+    print("Hello from my_task!", arg1, arg2)  # noqa: T201

docs/framework_integrations/faststream.md

@@ -0,0 +1,32 @@
+---
+order: 3
+---
+
+# Taskiq + FastStream
+
+[FastStream](https://faststream.airt.ai/latest/) is a library that allows you to write consumers and producers for different message brokers almost like taskiq. But the differense is that taskiq is more focused on tasks for a specific project and more like celery but async, while FastStream is more focused on events and defining how different systems communicate with each other using distributed brokers.
+
+If you want to declare communication between different projects you can use taskiq, but it might be a bit more complex than using FastStream.
+
+Although these libraries solve different problems, they have integration between each other, so you can use FastStream as a broker for taskiq. It allows FastStream to use taskiq's scheduler along with its own features.
+
+To use FastStream as a broker for taskiq you need to install the `taskiq-faststream` library:
+
+```bash:no-line-numbers
+pip install "taskiq-faststream"
+```
+
+And you can use it like this:
+
+```python
+from faststream import FastStream
+from faststream.kafka import KafkaBroker
+from taskiq_faststream import BrokerWrapper
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+taskiq_broker = BrokerWrapper(broker)
+```
+
+You can read more about scheduling tasks for FastStream in the [FastStream documentation](https://faststream.airt.ai/latest/scheduling/?h=schedule).

docs/framework_integrations/taskiq-with-aiogram.md

@@ -0,0 +1,102 @@
+# Taskiq + Aiogram
+
+[Taskiq-Aiogram](https://github.com/taskiq-python/taskiq-aiogram) is a nice integration with one of the best telegram bot libraries - [aiogram](https://docs.aiogram.dev/en/latest/).
+
+This integration allows you to easily send delayed messages or run intensive functions without blocking the message handing.
+
+This integration adds three main dependencies which you can use in your taskiq functions:
+
+- `aiogram.Bot` - the bot instance that you can use to send messages or perform other actions. If multiple bots listen to the same dispatcher, this dependency will be resolved to the latest bot passed in the `taskiq_aiogram.init` function.
+- `aiogram.Dispatcher` - current dispatcher instance.
+- `List[aiogram.Bot]` - list of all bots that were passed to the `taskiq_aiogram.init` function.
+
+To enable the integration, please install the `taskiq-aiogram` library:
+
+```bash:no-line-numbers
+pip install "taskiq-aiogram"
+```
+
+After the installation is complete, add an initialization function call to your broker's main file so it becomes something like this:
+
+```python title="tkq.py"
+import asyncio
+
+import taskiq_aiogram
+from aiogram import Bot
+from taskiq import TaskiqDepends
+from taskiq_redis import ListQueueBroker
+
+broker = ListQueueBroker("redis://localhost")
+
+# This line is going to initialize everything.
+taskiq_aiogram.init(
+    broker,
+    # This is path to the dispatcher.
+    "bot:dp",
+    # This is path to the bot instance.
+    "bot:bot",
+    # You can specify more bots here.
+)
+
+
+@broker.task(task_name="my_task")
+async def my_task(chat_id: int, bot: Bot = TaskiqDepends()) -> None:
+    print("I'm a task")
+    await asyncio.sleep(4)
+    await bot.send_message(chat_id, "task completed")
+
+```
+
+Let's see how to use this integration.
+
+```python title="bot.py"
+import asyncio
+import logging
+import sys
+
+from aiogram import Bot, Dispatcher, types
+from aiogram.filters import Command
+
+from tkq import broker, my_task
+
+dp = Dispatcher()
+bot = Bot(token="TOKEN")
+
+
+# Taskiq calls this function when starting the worker.
+@dp.startup()
+async def setup_taskiq(bot: Bot, *_args, **_kwargs):
+    # Here we check if it's a clien-side,
+    # Becuase otherwise you're going to
+    # create infinite loop of startup events.
+    if not broker.is_worker_process:
+        logging.info("Setting up taskiq")
+        await broker.startup()
+
+
+# Taskiq calls this function when shutting down the worker.
+@dp.shutdown()
+async def shutdown_taskiq(bot: Bot, *_args, **_kwargs):
+    if not broker.is_worker_process:
+        logging.info("Shutting down taskiq")
+        await broker.shutdown()
+
+
+## Simple command to handle
+@dp.message(Command("task"))
+async def message(message: types.Message):
+    await my_task.kiq(message.chat.id)
+
+
+## Main function that starts the bot.
+async def main():
+    await dp.start_polling(bot)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
+    asyncio.run(main())
+
+```
+
+That's it. Now you can easily call tasks from your bots and access bots from within your tasks.

docs/guide/architecture-overview.md

@@ -15,7 +15,7 @@ If you use dark theme and cannot see words on diagram,
 try switching to light theme and back to dark.
 :::
 
-```mermaid
+```sequence
 rect rgb(191, 223, 255)
 note right of Your code: Client side.
 Your code ->> Kicker: assemble message

docs/guide/scheduling-tasks.md

@@ -92,3 +92,79 @@ To avoid this behaviour, you can pass the `--skip-first-run` flag to the `taskiq
 ```bash:no-line-numbers
 taskiq scheduler module:scheduler --skip-first-run
 ```
+
+
+## Dynamic scheduling
+
+Sometimes you may want to add new schedules to the scheduler on the fly. For example, you may want to run a specific function in several minutes from now. You can easily do it with ScheduleSources that support dynamic scheduling. Currently we suggest to use the `RedisScheduleSource` for that purpose. List of schedulers with dynamic task addition will be extended in the future.
+For list of available schedule sources see [Available schedule sources](../available-components/schedule-sources.md).
+
+Here's an example of using redis schedule source:
+
+@[code python](../examples/schedule/redis_schedule.py)
+
+Now we can use this source to add new schedules in runtime. Here's an example:
+
+```python
+    await redis_source.startup()
+
+    await my_task.schedule_by_time(
+        redis_source,
+        # It's better to use UTC time, or add tzinfo to datetime.
+        datetime.datetime.utcnow() + datetime.timedelta(minutes=1, seconds=5),
+        # You can pass args and kwargs here as usual
+        11,
+        arg2="arg2",
+    )
+```
+
+Or if you want ot use cron schedules instead, just use `schedule_by_cron` method.
+
+```python
+    await my_task.schedule_by_cron(
+        redis_source,
+        "*/5 * * * *",
+        11,
+        arg2="arg2",
+    )
+```
+
+If you want to pass additional labels, you can call these methods on the `Kicker` instance.
+
+```python
+    schedule = (
+        await my_task.kicker()
+        .with_labels(label1="value")
+        .schedule_by_time(
+            redis_source,
+            datetime.datetime.utcnow() + datetime.timedelta(seconds=10),
+            11,
+            arg2="arg2",
+        )
+    )
+```
+
+::: warning Cool warning!
+
+The `with_broker` method won't do anything in this case, since we have a broker assigned to each scheduler.
+
+:::
+
+Each of these methods return you an instance of the `CreatedSchedule` class. This object has unique schedule ID and some helper methods. For example, you can use the `unschedule` method to remove the schedule from the source.
+
+```python
+    schedule = await my_task.schedule_by_time(
+        redis_source,
+        datetime.datetime.utcnow() + datetime.timedelta(minutes=1, seconds=5),
+        11,
+        arg2="arg2",
+    )
+
+    await schedule.unschedule()
+```
+
+Or it can be done manually, by calling `delete_schedule` on schedule source providing it whith `schedule_id`.
+
+```python
+    await redis_source.delete_schedule(schedule.schedule_id)
+```

package.json

@@ -11,11 +11,12 @@
   },
   "packageManager": "[email protected]",
   "devDependencies": {
-    "@vuepress/client": "2.0.0-rc.0",
-    "mermaid": "^10.6.1",
-    "vue": "^3.3.9",
-    "vuepress": "2.0.0-rc.0",
-    "vuepress-plugin-search-pro": "2.0.0-rc.1",
-    "vuepress-theme-hope": "2.0.0-rc.1"
+    "@vuepress/bundler-vite": "2.0.0-rc.6",
+    "mermaid": "^10.8.0",
+    "sass-loader": "^14.1.0",
+    "vue": "^3.4.15",
+    "vuepress": "2.0.0-rc.6",
+    "vuepress-plugin-search-pro": "2.0.0-rc.22",
+    "vuepress-theme-hope": "2.0.0-rc.22"
   }
 }