docs: add new user-oriented documentation

This new documentation is a work in progress, but it's already a step forward in making PyKorone increasingly intuitive and user-friendly for new users and people who aren't very familiar with bots.

https://pykorone.readthedocs.io/

README.md

@@ -5,8 +5,8 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Documentation Status](https://readthedocs.org/projects/pykorone/badge/?version=latest)](https://pykorone.readthedocs.io/en/latest/?badge=latest)
 [![Weblate](http://weblate.amanoteam.com/widget/korone/korone/svg-badge.svg)](http://weblate.amanoteam.com/engage/korone/)
-[![Channel](https://img.shields.io/badge/Follow-Telegram-blue.svg?logo=telegram)](https://t.me/PyKorone)
-[![GitHub License](https://img.shields.io/github/license/HitaloM/PyKorone?logo=bsd)](/LICENSE)
+[![Telegram](https://img.shields.io/badge/Telegram-blue.svg?logo=telegram)](https://t.me/PyKorone)
+[![License](https://img.shields.io/github/license/HitaloM/PyKorone?logo=bsd)](/LICENSE)
 
 PyKorone is a comprehensive, state-of-the-art Telegram bot that offers a variety of features to enhance your Telegram experience. It is designed to be flexible and adaptable to meet a wide range of user needs. The bot is built in Python and is designed for high efficiency and reliability.
 

docs/source/conf.py

@@ -19,39 +19,29 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "myst_parser",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
 ]
 
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-    "hydrogram": ("https://docs.hydrogram.org/en/latest/", None),
-    "babel": ("https://babel.pocoo.org/en/latest/", None),
-    "aiosqlite": ("https://aiosqlite.omnilib.dev/en/stable/", None),
-}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 html_use_modindex = False
 html_use_index = False
 
-napoleon_numpy_docstring = True
-napoleon_google_docstring = False
-napoleon_preprocess_types = True
-napoleon_use_rtype = False
-napoleon_use_param = False
-napoleon_use_admonition_for_examples = True
-
 master_doc = "index"
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 autodoc_member_order = "bysource"
 
-pygments_style = "friendly"
+pygments_style = "sphinx"
 autodoc_typehints = "none"
 
+html_static_path = ["_static"]
+html_logo = "_static/img/korone-alone.png"
 html_theme = "furo"
-html_title = f"{project} Docs - {release}"
+html_title = f"{project} {release} documentation"
 html_last_updated_fmt = f"{date_time.strftime("%d/%m/%Y, %H:%M:%S")} UTC"
 html_copy_source = False
 
@@ -65,7 +55,7 @@
     "footer_icons": [  # these icons are getten from: https://react-icons.github.io/react-icons/
         {
             "name": "Telegram",
-            "url": "https://t.me/PyKoroneBot/",
+            "url": "https://t.me/PyKorone/",
             "html": (
                 '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
                 'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'

docs/source/development/changelog.rst

@@ -0,0 +1,3 @@
+=========
+Changelog
+=========

docs/source/development/contributing.md

@@ -0,0 +1 @@
+# Contributing

docs/source/getting_started.md

@@ -0,0 +1,59 @@
+# Getting Started
+
+To get started with PyKorone, you need to add the bot to your group. This guide will walk you through the process of adding PyKorone to your group and granting it admin rights.
+
+## Introduction
+
+PyKorone is an all-in-one Telegram bot with a variety of features, such as:
+
+- Downloading YouTube videos and music
+- Downloading Twitter videos and images
+- Downloading TikTok videos
+- DeepL translation
+- GSM Arena phone search
+- Sticker stealer
+- ... and more!
+
+Setting up PyKorone is easy. To help you get started, this guide will walk you through the process.
+
+## Adding PyKorone to Your Group
+
+PyKorone is designed to work in groups. To add PyKorone to your group, follow these steps:
+
+### Instructions
+
+1. Open your Telegram client of choice.
+2. Do a user search for `@PyKoroneBot` (see note below).
+3. View the bot's profile, click the 3-dot menu in the top right corner, and select the `Add to Group` option. Then choose your group.
+
+Congratulations! PyKorone is now in your group.
+
+```{attention}
+During step 2, you may see other bots or users with similar names or usernames. Make sure you only add the bot with the username `@PyKoroneBot`, as others are imposters!
+```
+
+### Alternative Instructions
+
+If you're having trouble adding PyKorone to your group, you can use the following link to add PyKorone to your group: [Add PyKorone to Group](https://telegram.me/PyKoroneBot?startgroup=true).
+
+```{admonition} Note - Mobile Devices
+If you're on your mobile device, the link should open your Telegram client to select the chat you wish to add PyKorone to.
+```
+
+```{admonition} Note - PC Users
+If you're on a PC, you need to have Telegram Desktop installed. When the link opens in your browser, Telegram will ask you to allow it to open the link. Select "allow," and when Telegram opens, you should get a prompt to choose which group you'd like to add PyKorone to.
+```
+
+## Granting PyKorone Admin (Optional)
+
+To use PyKorone in groups, you don't need to give it admin rights, but it's recommended to do so to avoid some Telegram limitations. To give PyKorone admin rights, follow these steps:
+
+### Instructions
+
+1. Click the banner at the top of your group to view your group's information.
+2. Click the pencil icon to edit your group's settings.
+3. Click "Administrators," and then "Add Administrator."
+4. Select `@PyKoroneBot` from the list of users.
+5. Grant it all the admin rights available, and click the checkmark icon to confirm.
+
+Congratulations! PyKorone now has admin rights in your group.

docs/source/index.md

@@ -0,0 +1,55 @@
+# PyKorone: The State-of-the-Art Telegram Bot
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Documentation Status](https://readthedocs.org/projects/pykorone/badge/?version=latest)](https://pykorone.readthedocs.io/en/latest/?badge=latest)
+[![Weblate](http://weblate.amanoteam.com/widget/korone/korone/svg-badge.svg)](http://weblate.amanoteam.com/engage/korone/)
+[![Telegram](https://img.shields.io/badge/Telegram-blue.svg?logo=telegram)](https://t.me/PyKorone)
+[![GitHub License](https://img.shields.io/github/license/HitaloM/PyKorone?logo=bsd)](/license)
+
+PyKorone is a comprehensive, state-of-the-art Telegram bot that offers a variety of features to enhance your Telegram experience. It is designed to be flexible and adaptable to meet a wide range of user needs. The bot is built in Python and is designed for high efficiency and reliability.
+
+This documentation is your definitive guide to exploring and using PyKorone to the fullest. Here you'll find detailed information about its features, step-by-step instructions, and tips on how to get the most out of the bot. If you have any questions or need help, our community is ready to assist you at [PyKorone Discussions](https://github.com/HitaloM/PyKorone/discussions).
+
+## How the Documentation is Organized
+
+Contents are organized into sections composed of self-contained topics which can be accessed from the sidebar or by following them in order using the {guilabel}`Next` button at the end of each page.
+
+### User Guide
+
+- {doc}`Getting Started </getting_started>`: Overview to get you started.
+- {doc}`Usage and Configuration </usage_and_configuration/index>`: Learn how to use and configure.
+- {doc}`Privacy </privacy>`: Information about the data collected by PyKorone.
+
+### Development
+
+- {doc}`Contributing </development/contributing>`: Contributing guidelines.
+- {doc}`Changelog </development/changelog>`: Release notes.
+
+```{toctree}
+:maxdepth: 1
+:caption: User Guide
+:hidden:
+
+getting_started
+usage_and_configuration/index
+modules/index
+privacy
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Development
+:hidden:
+
+development/contributing
+development/changelog
+license
+```
+
+```{toctree}
+:caption: Project Links
+:hidden:
+
+GitHub <https://github.com/HitaloM/PyKorone>
+Telegram <https://t.me/PyKoroneBot>
+```

docs/source/license.md

@@ -0,0 +1,4 @@
+# License
+
+```{include} ../../LICENSE
+```

docs/source/modules/afk.md

@@ -0,0 +1,7 @@
+# AFK (Away From Keyboard)
+
+The AFK module is a simple module that allows users to set themselves as AFK. When a user is AFK, a message will be sent to any user that mentions them.
+
+## Commands
+
+- `/afk (?reason)`: Set yourself as AFK with an optional reason.

docs/source/modules/disabling.md

@@ -0,0 +1,20 @@
+# Disabling
+
+Not everyone wants every feature Korone offers. Some commands are best left unused to prevent spam and abuse.
+
+This allows you to disable some commonly used commands so that no one can use them.
+
+## Commands
+
+- `/disable (commandname)`: Disable user from using the "commandname" command.
+- `/enable (commandname)`: Enable user to use the "commandname" command.
+- `/disableable`: List all commands that can be disabled.
+- `/disabled`: List all commands that are currently disabled.
+
+````{note}
+This module is only available for groups.
+
+```{attention}
+Only users with the `administrator` permission can disable commands.
+```
+````

docs/source/modules/gsm_arena.md

@@ -0,0 +1,9 @@
+# GSM Arena
+
+Obtaining smartphone specifications can be a tedious task, especially when it involves navigating through multiple websites or pages.
+
+This module simplifies the process by enabling users to obtain the specifications of a particular device directly from Telegram using data from [GSM Arena](https://www.gsmarena.com/).
+
+## Commands
+
+- `/d (device name)`: When you provide the name of a device, the bot will search for it on GSM Arena and return a list of devices matching the search query. You can then select a device from the list to view its specifications. Or if the device is unique, the bot will directly display its specifications.

docs/source/modules/index.md

@@ -0,0 +1,48 @@
+# Modules
+
+```{toctree}
+---
+hidden:
+---
+
+afk
+disabling
+gsm_arena
+languages
+lastfm
+medias
+stickers
+translator
+users_groups
+web
+```
+
+PyKorone's modules are a collection of commands grouped by functionality. Each module serves a specific purpose and provides commands to interact with the bot. These commands can take arguments to customize the output, with both mandatory and optional arguments detailed in each command's description.
+
+## Understanding Command Arguments
+
+When you see a command in the documentation, it may have one or more arguments that you need to provide. The arguments are enclosed in parentheses `()`, and some of them may be optional, indicated by a question mark `?` before the argument name. For example, the command `/command (user) (?text)` requires the `user` argument and has an optional `text` argument.
+
+```{note}
+**Argument Types:**
+
+- `()`: Required argument.
+- `(user)`: Required (user ID or username), but you can also reply to any user's message as an alternative.
+- `(group)`: Required (group ID or username).
+- `(? )`: Optional argument.
+```
+
+## Available Modules
+
+Below is an overview of the modules available in PyKorone, along with a brief description of their functionalities:
+
+- {doc}`AFK (Away From Keyboard) <afk>`: Enables you to set your status as AFK.
+- {doc}`Disabling <disabling>`: Allows you to disable specific commands to prevent spam and abuse.
+- {doc}`GSM Arena <gsm_arena>`: Fetches smartphone specifications from GSM Arena.
+- {doc}`Languages <languages>`: Lets you change the bot's language.
+- {doc}`LastFM <lastfm>`: Retrieves your LastFM scrobbles.
+- {doc}`Medias <medias>`: Downloads media from various websites.
+- {doc}`Stickers <stickers>`: Manipulates stickers and sticker sets.
+- {doc}`Translator <translator>`: Translates text between languages using DeepL.
+- {doc}`Users & Groups <users_groups>`: Fetches information about users and groups.
+- {doc}`Web Tools <web>`: Retrieves information about IP addresses and domains.

docs/source/modules/languages.md

@@ -0,0 +1,22 @@
+# Languages
+
+Not every group speaks fluent english; some groups would rather have PyKorone respond in their own language.
+
+This is where translations come in; you can change the language of the bot's replies to be in the language of your choice!
+
+## Commands
+
+- `/language`: Displays the current language of the bot in the chat.
+- `/languages`: Displays a list of all available languages. To set a new language, just click on the button corresponding to the language you want.
+
+```{warning}
+In groups, only admins can change the language of the bot.
+```
+
+## Contribute to Translations
+
+Help make PyKorone available in your language by contributing translations via Weblate. You can access the project [here](https://weblate.amanoteam.com/projects/korone/korone/).
+
+```{note}
+Translations from Weblate will be integrated into PyKorone with every new release.
+```

docs/source/modules/lastfm.md

@@ -0,0 +1,37 @@
+# LastFM
+
+The LastFM module allows you to get and view information about your favorite artists, albums and tracks. You can also view your recent plays and share them with your friends.
+
+## Commands
+
+- `/setlfm (your username)`: Set your LastFM username.
+- `/lfm`: Get the track you are currently listening to or the last track you listened to.
+- `/lfmrecent`: Get your last 5 played tracks.
+- `/lfmartist`: Get the artist you are currently listening to or the last artist you listened to.
+- `/lfmalbum`: Get the album you are currently listening to or the last album you listened to.
+- `/lfmuser`: Get your total scrobbles, tracks, artists, and albums scrobbled.
+- `/lfmtop (?type)`: Get your top artists, tracks, or albums (defaults to artists).
+- `/lfmcompat`: Get the compatibility of your music taste with another user.
+- `/lfmcollage (?size) (?period)`: Get a collage of your top albums (defaults to `3x3` and `all`).
+
+```{note}
+**Supported sizes**: `1`, `2`, `3`, `4`, `5`, `6`, `7`
+
+**Supported periods**: `1d`, `7d`, `1m`, `3m`, `6m`, `1y`, `all`
+
+**Supported types**: `artist`, `track`, `album`
+```
+
+### Examples
+
+- Generate a collage of your top 5x5 albums in a period of 7 days:
+  - `/lfmcollage 5 7d`
+
+- Generate a collage of your top 7x7 albums in a period of 1 month without text:
+  - `/lfmcollage 7 1m clean`
+
+- Get your top 5 artists in a period of 1 year:
+  - `/lfmtop 1y`
+
+- Get your top 5 tracks of all time:
+  - `/lfmtop track`

docs/source/modules/medias.md

@@ -0,0 +1,14 @@
+# Medias
+
+Some websites, when their links are shared on Telegram, do not display a preview of the content. This module solves this problem by automatically downloading the media content from these websites and displaying it in the chat.
+
+```{note}
+**Automatic media download is available for the following websites**:
+- X (Twitter)
+- TikTok
+```
+
+## Commands
+
+- `/ytdl (?URL)`: Download a video or audio from YouTube. You can
+also omit the link and reply to a message containing a YouTube URL.

docs/source/modules/stickers.md

@@ -0,0 +1,16 @@
+# Stickers
+
+The stickers module provides commands to manage stickers and sticker sets in Telegram. You can use these commands to steal stickers from other sets, create new sticker sets, and add stickers to existing sets.
+
+## Commands
+
+- `/getsticker`: Fetches the sticker from the replied message and sends it to the chat as a file.
+- `/kang (?emoji)`: Steals the sticker from the replied message and adds it to a new sticker set or an existing one. If you provide an emoji, the bot will use it as the sticker's emoji.
+
+```{note}
+Currently, the `/kang` command only supports adding stickers to sticker packs created by the bot. You can't add stickers to other people's sticker packs or to sticker packs you created manually.
+```
+
+```{hint}
+the `/kang` command can be used in reply to images and videos as well.
+```