Implement docs

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements-docs.txt
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -3,3 +3,4 @@
 __pycache__
 *.swp
 .env*
+site/

README.md

@@ -1,12 +1,13 @@
 # Hammett
 
 Hammett is a framework whose main goal is to simplify building *commercial* Telegram bots with clear code and a good architecture. By commercial bots are meant such bots that require the support of
-* several roles of users (admin, beta testers, moderators, etc.) to manage the visibility of some parts of the user interface;
-* the permissions mechanism to implement a **maintenance mode**, **paywall**, etc.
-* storing the users state in and restoring it from Redis.
+
+  * several roles of users (admin, beta testers, moderators, etc.) to manage the visibility of some parts of the user interface;
+  * the permissions mechanism to implement a **maintenance mode**, **paywall**, etc.
+  * storing the users state in and restoring it from Redis.
 
 <p align="center">
-    <img src="/logo/1500x1299.png" alt="Hammett" style="max-width: 100%; width: 500px">
+    <img src="/assets/images/logo.png" alt="Hammett" style="max-width: 100%; width: 500px">
 </p>
 
 ## Authors

docs/docs/application.md

@@ -0,0 +1,3 @@
+# Hammett Core
+
+::: hammett.core

docs/docs/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions
+
+::: hammett.core.exceptions

docs/docs/hiders.md

@@ -0,0 +1,3 @@
+# Hiders
+
+::: hammett.core.hiders

docs/docs/permissions.md

@@ -0,0 +1,3 @@
+# Permissions
+
+::: hammett.core.permissions

docs/docs/screen.md

@@ -0,0 +1,3 @@
+# Screen
+
+::: hammett.core.screen

docs/getting_started/AUTHORS.md

@@ -0,0 +1 @@
+--8<-- "AUTHORS.md"

docs/getting_started/demos.md

@@ -0,0 +1,6 @@
+# Demos
+
+You can find code samples on [GitHub](https://github.com/cusdeb-com/hammett/tree/main/demos).
+
+If there are ideas of what other demo you would like to see you
+can [create an Issue](https://github.com/cusdeb-com/hammett/issues/new) with the suggestion.

docs/getting_started/index.md

@@ -0,0 +1,30 @@
+# Getting started
+
+## Installation
+
+### with pip <small>recommended</small>
+
+Hammett is published as a [Python package] and can be installed with
+`pip`, highly recommended to use a [virtual environment]. Open up a terminal and install with:
+
+``` sh
+pip install <package>
+```
+
+### with git
+
+Hammett can be installed directly from [GitHub]
+```
+git clone https://github.com/cusdeb-com/hammett.git
+```
+
+After cloning from `git`, you must install all required dependencies with:
+
+```
+pip install -r requirements.txt
+```
+
+
+[Python package]: https://pypi.org/project/<package>/
+[GitHub]: https://github.com/cusdeb-com/hammett
+[virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment

docs/getting_started/introduction.md

@@ -0,0 +1,139 @@
+# Introduction
+
+Hammett зиждется на трех аккордах (или китах, если хотите): Screens, Permissions и Hiders. В простейшем случае
+пользователь, работая с ботом, переходит от одного экрана к другому, поэтому Screen'ы являются краеугольным камнем
+ботов на Hammett. Продвинутые боты, в свою очередь, могут предусматривать разные роли и разрешения для пользователей.
+В этом случае на сцену выходят Hider'ы и Permission'ы. Hider'ы позволяют управлять видимостью кнопок на каждом
+Screen'е в зависимости от роли пользователя, а Permission'ы позволяют управлять видимостью экранов в зависимости от
+прав пользователя. Теперь давайте разберем каждый из этих аккордов по отдельности.
+
+## Screens
+
+Screen – это абстракция над обычным Telegram-сообщением для удобного управления его состоянием. Screen’ы представляются
+классом Screen. Основная задача этого класса – предоставлять разработчикам возможности для отрисовки и дальнейшей
+перерисовки контента. Контент screen'а может состоять из следующих компонентов:
+
+1. cover – это изображение, которое будет отправлено вместе с сообщением;
+2. description или document. description – это текст сообщения, который может содержать HTML-теги (см. какие теги могут
+   использоваться в описаниях), а document – это любой файл;
+3. keyboard – это одна или более кнопок (см. какие типы кнопок могут использоваться в клавиатурах);
+
+```python3
+from hammett.core import Screen
+
+
+class SimpleScreen(Screen):
+    cover = 'https://upload.wikimedia.org/wikipedia/commons/2/28/M_Metallica_Userbox.PNG'
+    description = 'Some text'
+```
+
+Screen может существовать при наличии хотя бы одного из этих компонентов. Стоит заметить, что на экране эти компоненты
+располагаются строго в том порядке, в котором они перечислены в списке выше. Повлиять на этот порядок нельзя.
+
+Для управления отрисовкой есть несколько вариантов:
+
+1. Статически через атрибуты Screen’а.
+2. Динамически через специальные методы Screen’а.
+
+Статичный контент задается в атрибутах Screen’а. Это удобно если вам всегда нужно отправлять текст и/или это изображение
+пользователю в чат без каких либо условий. Если же контент должен генерироваться по каким-то условиям или, например,
+запрашиваться по API, то вам нужно переопределить методы и уже там указать нужное вам поведение. Для cover соотносится
+get_cover, для description соотносится get_description и т.д.
+
+Также важная задача Screen’а — предоставлять удобный механизм переключения между разнымы Screen’ами. Для этого есть 2
+метода, goto и jump:
+
+1. goto - используется, когда нужно перейти от текущего Screen'а к другому, перерисовав текущий;
+2. jump - используется, когда нужно перейти от одного Screen'а к другому, отрисовав этот экран как новое сообщение.
+
+   	… тут пример
+
+### RenderConfig
+
+Класс данных (dataclass) - хранит в себе параметры, связанные с отрисовкой. Все статичные и/или динамические параметры
+так или иначе попадут в RenderConfig перед вызовом метода отрисовки. Этот класс можно явно указывать при вызове метода
+отрисовки, чтобы также влиять на контент и на само поведение отрисовки.
+
+Тут пример
+…
+
+	Приоритет параметров при отрисовке (тут будет красивое изображение):
+
+	RenderConfig -> Static -> Dinamic (if overridden)
+
+Обычно RenderConfig явно конфигурируется при переопределении методов goto и jump (см. Маршрутизация между Screen’ами).
+Если требуется задать одинаковое поведение для всех случаев отрисовки нужно переопределить метод get_config, который
+должен вернуть объект RenderConfig:
+
+Тут пример
+…
+
+### Обработчики
+
+Есть три типа обработчиков:
+
+1) обработчик нажатия на кнопку;
+2) обработчик пользовательского ввода;
+3) обработчик команды (пример: /command).
+
+Чтобы зарегистрировать метод Screen’а как обработчик нужно обернуть его в декоратор, метод обязательно должен иметь в
+качестве аргументов self, update и context. Давайте разберем каждый из этих типов обработчиков по отдельности.
+
+Обработчик нажатия на кнопку привязывается к кнопке на клавиатуре и срабатывает при нажатии на неё.
+
+Тут пример…
+
+Обработчик пользовательского ввода срабатывает на какое-либо сообщение от пользователя, например отправку текстового
+сообщения или отправку изображения. Можно конкретизировать на какой контент он может сработать см. Filters.
+
+Тут пример…
+
+Обработчик команды срабатывает на отправку команды от пользователя, например /say_hi.
+
+Тут пример…
+
+### Скрытие клавиатуры
+
+Позволяет убирать у предыдущих Screen’ов клавиатуру, оставляя её только у последнего (latest) Screen’а. Это делает
+историю сообщений более читаемой и не дает пользователю нажать кнопки, которые в данный момент не нужны.
+
+После каждой отрисовки Screen’а как новое сообщение будет удалятся клавиатура у предыдущего сообщения и только у него,
+больше чем у одного предыдущего сообщения клавиатура удалятся не будет.
+
+Примечание: чтобы включить эту возможность, нужно установить значение параметра конфигурации SAVE_LATEST_MESSAGE в True:
+
+Тут пример:
+
+Ссылка на демо.
+
+## Permissions
+
+Позволяют быстро настроить права доступа в боте. Вот пара примеров, в каких случаях могут использоваться Persmission'ы:
+
+- Регистрация, которую обязан пройти пользователь, чтобы получить разрешение использовать сервис, который
+  предоставляется ботом.
+- Paywall, когда пользователь не имеет разрешения продвинутся дальше, пока не оформит подписку на бота.
+
+  Permission’ы могут накладываться друг на друга, если проверок может быть несколько. В каждом Permission’е нужно
+  объявить проверку в методе has_permission и что нужно сделать, если доступа нет в методе handle_permission_denied.
+
+… тут пример
+
+Все объявленные Permission’ы также должны быть указаны в конфигурационном файле, например:
+
+```python3
+PERMISSIONS = [
+    'app.permissions.NamePermission',
+]
+```
+
+Можно игнорировать Permission’ы, обернув в декоратор обработчик и указав какие Permission’ы мы хотим проигнорировать.
+Важно: декоратор ignore_permissions должнен быть выше чем декоратор для регистрации обработчика:
+
+```python3
+@ignore_permissions([NamePermission])
+@register_button_handler
+async def handle_something(self, update, context):
+    """Some code"""
+```
+