docs: first version

#29

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: docs
+on:
+  push:
+    branches:
+      - master
+      - 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 mkdocs-material
+      - run: mkdocs gh-deploy --force

docs/howto.md

@@ -0,0 +1,83 @@
+# C чего начать
+
+## Установка
+
+Чтобы установить актуальную версию клиента, воспользуйтесь командой:
+
+```text
+pip install -U yatracker
+```
+
+## Инициализация и завершение работы
+
+Импортируйте библиотеку
+
+```python
+from yatracker import YaTracker
+```
+
+Создайте экземпляр, передав в конструктор класса необходимые секреты
+
+```python
+from yatracker import YaTracker
+
+tracker = YaTracker(org_id=..., token=...) # (1)
+```
+
+1. Не сохраняйте свои учётные данные прямо в коде. Используйте переменные окружения.
+
+Для работы с одной организацией достаточного одного клиента.
+Вы один раз создаёте его и далее повторно используете его при необходимости.
+
+Не забудьте завершить работу клиента при закрытии вашего приложения
+
+```python
+async def on_shutdown():
+    await tracker.close()
+
+```
+
+
+## Использование
+
+!!! Внимание
+
+    Все методы `YaTracker`, вызывающие API, являются асинхронными.
+    Ссоответственно, вызывать их нужно внутри корутин.
+    Но для упрощения примеров они будут использованы напрямую, как будто мы находимся уже внутри функции.
+
+    Т.е. вместо
+    ```python
+    async def foo(...):
+        await method(...)
+    ```
+    Мы будем писать
+    ```python
+    await method(...)
+    ```
+
+
+
+Для начала создадим новую задачу в очереди для писателей
+```python
+issue = await tracker.create_issue('Написать шедевр', 'WRITERS') # (1)
+```
+
+1. `WRITERS` – ключ очереди
+
+Дополним задачу описанием
+```python
+issue = await tracker.edit(
+    issue_id='WRITERS-1',
+    description='... или нечто ценное' # (1)
+)
+
+```
+
+1. Описание можно было задать ещё при создании, а здесь это лишь повод для редактирования.
+
+Если вам известен ключ задачи, то нетрудно её получить
+
+```python
+issue = await tracker.get_issue('WRITERS-42')
+```

docs/index.md

@@ -0,0 +1,8 @@
+# О библиотеке
+
+YaTracker представляет собой асинхронный клиент на python для удобной работы с API Яндекс.Трекера.
+
+## Предостережение
+
+Данная библиотека работает **только** с асинхронными приложениями,
+и требует наличия базовых навыков работы с python.

mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: YaTracker
+theme:
+  name: material
+  language: ru
+
+  palette:
+    primary: blue
+
+  features:
+    - content.code.copy
+    - content.code.annotate
+
+plugins:
+  - mkdocstrings
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - admonition
+  - pymdownx.details

pyproject.toml

@@ -53,6 +53,10 @@ test = [
     "pytest-asyncio>=0",
     "pytest-cov>=4",
 ]
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
 
 
 [project.urls]