Merge branch 'usernein:master' into master

.github/workflows/deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+    # Review gh actions docs if you want to further define triggers, paths, etc.
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    env:
+      working-dir: ./docs
+    defaults:
+        run:
+            working-directory: ${{ env.working-dir }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: ./docs/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build website
+        run: yarn build
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docs/build
+          cname: pyromod.pauxis.dev
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/test-deploy.yml

@@ -0,0 +1,32 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - master
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    env:
+      working-dir: ./docs
+    defaults:
+        run:
+            working-directory: ${{ env.working-dir }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: ./docs/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -1,37 +1,41 @@
-# pyromod
+# Website
 
-[![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?style=flat&logo=telegram&logoColor=white)](https://t.me/pyromodchat)
-![GitHub release (latest by date)](https://img.shields.io/github/v/release/usernein/pyromod)
-[![Downloads](https://static.pepy.tech/badge/pyromod)](https://pepy.tech/project/pyromod)
-[![Downloads](https://static.pepy.tech/badge/pyromod/month)](https://pepy.tech/project/pyromod)
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-pyromod is a versatile Python add-on for the Pyrogram library, designed to make developing Telegram bots faster and more
-efficient.
+### Installation
 
-It's based on **monkeypatching**, which means it works together with Pyrogram, rather than being a fork or modified
-version. It
-adds features to Pyrogram classes on the go, so you don't need to update it every time Pyrogram is updated.
+```
+$ yarn
+```
 
-Whether you're building a simple chatbot or a complex form to get multiple responses from the user, pyromod has you
-covered. It enhances Pyrogram with a range
-of advanced features, simplifies conversation handling, and offers a high degree of customizability.
+### Local Development
 
-## Key Features
+```
+$ yarn start
+```
 
-- **Effortless Bot Development:** pyromod streamlines the process of building conversational Telegram bots, saving you
-  time and effort
-  during development.
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-- **Advanced Conversation Management:** Managing conversations with users is made easier, allowing you to create dynamic
-  and interactive interactions much easier, without having to save states anywhere, by leveraging the power of
-  async/await syntax.
+### Build
 
-- **Effortless Inline Keyboards Creation:** Creating inline keyboards is easier than ever with pyromod's inline keyboard
-  helper functions.
+```
+$ yarn build
+```
 
-- **User-Friendly Pagination:** Enhance the user experience by providing easy navigation tools with the pyromod's
-  pagination
-  helpers.
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-- **Highly Customizable:** pyromod's configuration options let you customize its behavior to meet your specific project
-  requirements.
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/get-started/configuration.md → docs/docs/getting-started/configuration.md

@@ -1,4 +1,7 @@
-## Configuration
+---
+title: Configuration
+sidebar_position: 4
+---
 
 pyromod offers various configuration options to customize its behavior according to your specific needs. This guide will walk you through the process of configuring pyromod using the `pyromod.config` object.
 

docs/get-started/examples.md → docs/docs/getting-started/examples.md

@@ -1,24 +1,27 @@
-## Examples
+---
+title: Examples
+sidebar_position: 5
+---
 
-**Awaiting a single message from a specific chat:**
+## Awaiting a single message from a specific chat
 
 ```python
 response = await client.listen(chat_id=chat_id)
 ```
 
-**Awaiting a single message from a specific user in a specific chat:**
+## Awaiting a single message from a specific user in a specific chat
 
 ```python
 response = await client.listen(chat_id=chat_id, user_id=user_id)
 ```
 
-**Asking the user a question then await for the response:**
+## Asking the user a question then await for the response
 
 ```python
 response = await client.ask(chat_id=chat_id, text='What is your name?')
 ```
 
-**Asking the user a question then await for the response, with a timeout:**
+## Asking the user a question then await for the response, with a timeout
 
 ```python
 try:
@@ -27,7 +30,7 @@ except ListenerTimeout:
     await message.reply('You took too long to answer.')
 ```
 
-**Full handler example, getting user's name and age with bound method Chat.ask:**
+## Full handler example, getting user's name and age with bound method Chat.ask
 
 ```python
 from pyromod import Client, Message
@@ -44,7 +47,7 @@ async def on_form(client: Client, message: Message):
     await message.reply(f'Your name is {name.text} and you are {age.text} years old.')
 ```
 
-**Easier inline keyboard creation:**
+## Easier inline keyboard creation
 
 ```python
 from pyromod.helpers import ikb

docs/docs/getting-started/initialization.md

@@ -0,0 +1,33 @@
+---
+title: Initialization
+sidebar_position: 3
+---
+
+To initialize pyromod, on the file that creates the client instance, simply import the Client class from pyromod instead
+of pyrogram:
+
+```python
+from pyromod import Client
+```
+
+And that's all! You can still use the `Client` class as you would normally do with Pyrogram, but now having all the
+extra features.
+
+:::note
+
+You don't need to change the imports on the plugins files. Even by importing `Client` from pyrogram, the pyromod  features will be available anyway.
+
+:::
+
+:::note
+
+In order to monkeyatch pyromod features successfully, it's just required that the  first `Client` class imported to your project code should be from pyromod. Then all the other future `Client` instances  will be patched automatically.
+
+:::
+
+:::note
+
+On custom plugins, you just need to import Client from pyromod if you want your IDE to recognize and suggest
+the extra features based on `pyromod.Client` type.
+
+:::

docs/docs/getting-started/installation.md

@@ -0,0 +1,33 @@
+---
+title: Installation
+sidebar_position: 2
+---
+
+To get started with pyromod, you can install it using pip:
+
+```bash
+pip install pyromod
+```
+
+Or poetry:
+
+```bash
+poetry add pyromod
+```
+
+Or rye:
+
+```bash
+rye add pyromod
+```
+:::note
+
+pyromod **requires** pyrogram to be installed, since it's a plugin that only does monkeypatching, rather than a standalone fork of pyrogram.
+
+:::
+
+:::info
+
+You can use pyromod natively if you are using Hydrogram instead of Pyrogram, since Hydrogram is a (hugely optimized) fork of Pyrogram that already includes pyromod built-in.
+
+:::