«Клюква» — автоматизация документации проектов на Python
Привет!
Меня зовут Алексей Фоменко.
Я разработчик из Нижнего Новгорода.
Сегодня хочу рассказать вам о своем сервисе «Клюква».
Почему «Клюква» и «автоматизация документации»?
Ответ на самом деле простой — потому что мне это название нравится.
Оно вызывает улыбку, какие-то ассоциации, поднимает настроение.
А когда мы имеем дело с документацией, особенно с ее написанием, улыбка и настроение обычно пропадают…
Ну и вы наверняка слышали выражение «Развесистая клюква».
Если что, в Википедии есть даже отдельная статья по этому поводу.
«Развесистая клюква» или просто «Клюква» в общем виде означает ложные или искаженные представления о чем‑либо.
Как раз здесь мы приходим к написанию документации.
К сожалению, составить и поддерживать документацию в актуальном состоянии — это проблема.
Скорее всего проблема в том числе и в вашей компании.
Здесь есть как субъективные факторы, когда не хватает кнутов и пряников, так и факторы объективные: новые бизнес задачи, выкатка новых фич, чем больше задач мы решаем, тем больше изменений вносится в проект, и, соответственно, тем быстрее устаревает документация.
И когда смотришь на весь этот процесс, который происходит постоянно, хочется его как‑то автоматизировать?
Именно это я попытался сделать с помощью сервиса «Клюква».
С помощью «Клюквы» вы можете:
строить диаграммы зависимостей, аналогичных UML
генерировать документацию, код, юнит тесты с использованием ИИ
задавать вопросы ИИ в контексте всего проекта или отдельного модуля
генерировать код на основе диаграмм зависимостей
Основные компоненты и принцип работы сервиса подробно описаны в инструкции.
Давайте посмотрим на примерах.
Перед вами одиниз модулей сервиса «Клюква». Желтым цветом обозначаются встроенные Python библиотеки, синим — сторонние библиотеки, ну, а зеленым обозначаются модули самого проекта.
Вы можете проходить в нужную вам директорию, выбрать интересующий вас модуль, посмотреть его зависимости, потом пройти дальше и посмотреть на классы модуля, изучить зависимости отдельного класса, его структуру, атрибуты, методы и т. д.
Диаграммы посмотрели, давай перейдем к генерации текста.
Текст документации создается по шаблону:
краткое описание модуля
описание классов и методов
описание зависимостей модуля
Также в «Клюкве» есть возможность работы с ИИ в формате вопрос‑ответ, при этом в контексте ИИ находится код всего проекта.
При необходимости контекст можно уточнить, послав путь необходимого вам модуля или группы модулей.
# cranberrypy/chat.py
MODULE_PATHS = """
/home/aleksei/development/cranberrypy/core/assistant/chains/base.py
/home/aleksei/development/cranberrypy/core/assistant/chains/custom_openai.py
/home/aleksei/development/cranberrypy/core/assistant/chains/factory.py
/home/aleksei/development/cranberrypy/core/assistant/chains/gemini.py
/home/aleksei/development/cranberrypy/core/assistant/chains/mistral.py
"""
Мы рассмотрели генерацию текста на основе текста.
Но в «Клюкве» есть возможность генерировать код на основе UML диаграмм.
Происходит это следующим образом:
Вы рисуете диаграммы, в модулях пишите необходимые свойства или функции класса.
Сохраняете диаграмму в JSON-файл.
Отправляете путь к JSON-файлу в чат ИИ.
Выглядит примерно так.
# Генерация кода для класса Customer
# Сравните полученный ответ с описанием класса в UML диаграмме
# core/market/clients/customer.py
from core.market.clients.person import Person
from core.market.cards.card import Card
from core.market.products.product import Product
from core.market.discount.discount import Discount
class Customer(Person):
"""
Represents a customer. Inherits from Person.
Attributes:
cards (list): List of the customer's cards.
balance (float): The customer's balance.
bucket (list): List of products in the customer's bucket.
"""
def __init__(self, name: str, age: int, address: str,
phone: str, cards: list = None, balance: float = 0.0):
super().__init__(name, age, address, phone)
self.cards = cards if cards is not None else []
self.balance = balance
self.bucket = []
def get_cards(self) -> list:
return self.cards
def get_balance(self) -> float:
return self.balance
def get_bucket(self) -> list:
return self.bucket
def add_to_bucket(self, product: Product, quantity: int,
discount: Discount = None) -> None:
"""
Adds a product to the customer's bucket.
Args:
product (Product): The product to add.
quantity (int): The quantity of the product to add.
discount (Discount, optional): The discount to apply. Defaults to None.
Raises:
ValueError: If balance is insufficient, gross amount mismatch, or weight limit exceeded.
"""
# Check balance and gross amount
gross_amount = product.get_price() * quantity
if discount:
if discount.get_condition() in product.get_name(): # Assuming condition is based on product name
gross_amount *= (1 - discount.get_percent())
if self.balance < gross_amount:
raise ValueError("Insufficient balance")
# Check weight limit
total_weight = product.get_weight() * quantity
if total_weight > 5:
raise ValueError("Weight limit exceeded (5 kg)")
# Add to bucket
self.bucket.append({'product': product, 'quantity': quantity,
'gross_amount': gross_amount})
self.balance -= gross_amountЕсли кто захочет попробовать, рекомендую подгружать в контекст какой-нибудь проект, где используются аналогичные библиотеки, и делать частями, по диаграмме сверху вниз, если сущности большие или их много.
PyCharm Professional vs Клюква
Чтобы понять плюсы и минусы сервиса, давайте сравним функционал «Клюквы» с одним из наиболее популярным инструментов для работы с кодом на Python — PyCharm.
В PyCharm Professional из под коробки доступны и построение диаграмм, и генерация кода, юнит тестов, комментариев с помощью AI Assistant.
Сравнивать будем по трем категориям:
построение диаграмм
генерация кода
генерация текста
Здесь я сразу оговорюсь, что у меня свой опыт использования PyCharm. Я прочитал инструкции. Что не смог сделать — пытался найти. Если вдруг я буду утверждать, что это невозможно, но вы знаете как, пожалуйста, напишите в комментарии. Будем вместе учиться.
Ну поехали.
Построение диаграммы
Плюсы:
На мой взгляд, основной плюс PyCharm в сравнении с «Клюквой» — всё встроено в одно IDE, не надо никуда ходить, заполнять конфиги, всё под рукой.
В PyCharm есть полноценный редактор, в котором можно изменять диаграммы, редактировать, переходить к источнику кода. Также очень крутая штука, что можно экспортировать диаграммы в разных форматах. В «Клюкве» только JSON.
Построение длинной цепочки зависимостей класса. В Клюкве отображаются прямые зависимости.
Минусы:
Полноценный редактор — это безусловно плюс, но это и минус. Он зачастую медленно работает и прогружает, особенно если много сущностей одновременно.
В PyCharm почему‑то отображаются только импорты.
В PyCharm невозможно переходить между объектами через диаграммы.
Итог:
Когда вам необходимо делать документацию, если прям необходимо рисовать‑рисовать, я бы наверно использовал PyCharm. А когда, например, проводить митинг или не надо много рисовать, то однозначно «Клюкву».
Генерация кода
Плюсы:
Удобство PyCharm — все встроено в IDE + окошко чата, что явный плюс. В «Клюкве» пока только командная строка.
Минусы:
В PyCharm из коробки отсутствует выбор LLM моделей. В «Клюкве» выбор моделей доступен, в том числе и запуск локально.
В PyCharm доступны несколько стандартных способ для быстрого создания промпта в ИИ, но нет возможности добавления новых шаблонов или их кастомизации. В «Клюкве» на уровне кода можно добавить любой промпт и настроить добавление контекста.
В случае текстового запроса преимущество «Клюквы» станет явным, когда вам необходимо использовать не один модуль, а сразу несколько. Достаточно указать пути к необходимым файлам (копировать‑вставить), и они подгрузятся в контекст.
В «Клюкве» доступна генерация кода на основе UML диаграмм, в PyCharm из коробки я не нашел.
Скажем честно, редактор UML диаграмм «Клюквы» сделан на коленке, поэтому говорить о полноценной работе функционала пока рано. Но это уже сейчас возможно, и я пробовал использовать редактор и последующую генерацию кода на коммерческих задачах. Пока не супер удобно, но помогает сократить время от обсуждения архитектуры до написания кода, так как то, что вы только что обсудили с коллегами можно тут же закинуть в ИИ и получить шаблоны вашего будущего сервиса.
Итог:
Если необходимо сгенерить небольшой код прямо здесь и сейчас — PyCharm.
Для более сложных задач, особенно при необходимости подключения контекста или обеспечения конфиденциальности данных — «Клюква».
Генерация текста
Плюсы:
Удобство PyCharm.
Минусы:
Отсутствие выбора LLM моделей.
Нет возможности добавления новых шаблонов или их кастомизации.
В «Клюкве» удобнее генерить общую документацию в README или для базы знаний, так как есть возможность работы сразу с несколькими модулями и кастомизировать шаблон документации.
Помимо кода и диаграмм зависимостей, в «Клюкву» несложно самостоятельно подключить любой необходимый вам контекст, будто файлы README, Confluence, Jira и тд.
Итог:
Быстро и для небольших задач — PyCharm, в остальных ситуациях — «Клюква».
Здесь самое время вспомнить про анекдот времен запуска ChatGPT
Профессия «промпт‑инженер» не успела появиться, как ее уже автоматизировали.
Да, именно это и делает «Клюква». На основе выбранных вами модулей динамически формируется целая портянка запроса плюс добавляется необходимый контекст.
В PyCharm и AI Assistant в данный момент нет возможности автоматизировать сложные промпты, но, я надеюсь подобный функционал появится в будущем.
Может быть даже благодаря «Клюкве» ;-)
Кстати, о планах.
Цель данной статьи не только порекламировать новый сервис для автоматизации документации, а в первую очередь найти людей, кто готов поучаствовать в его разработке.
Потому что проект подошел к той стадии, когда только моих знаний и умений явно недостаточно, по крайней мере, чтобы получить полноценный качественный продукт.
А между тем идеи для развития «Клюквы» есть.
Начнем от более реалистичных и наименее затратных до сложных, но перспективных:
сделать UI в браузере
написать расширение для IDE
включить сервис в систему CI/CD
разработать способ добавления бизнес информации в код проекта, чтобы в дальнейшем его можно было использовать для визуализации диаграмм бизнес процессов и генерации документации
Если вам лично или вашей компании будет интересно решить какую‑нибудь из этих задач, буду рад помочь и поучаствовать.
Если у вас есть идеи или предложения — пишите fomenko_ai@proton.me, обсудим.
Благодарю за внимание!
Habrahabr.ru прочитано 6187 раз
