«Клюква» — автоматизация документации проектов на 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 диаграмм.

Происходит это следующим образом:

1. Вы рисуете диаграммы, в модулях пишите необходимые свойства или функции класса.

2. Сохраняете диаграмму в JSON-файл.

3. Отправляете путь к 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 в данный момент нет возможности автоматизировать сложные промпты, но, я надеюсь подобный функционал появится в будущем.

Может быть даже благодаря «Клюкве» ;-)

Кстати, о планах.

Цель данной статьи не только порекламировать новый сервис для автоматизации документации, а в первую очередь найти людей, кто готов поучаствовать в его разработке.

Потому что проект подошел к той стадии, когда только моих знаний и умений явно недостаточно, по крайней мере, чтобы получить полноценный качественный продукт.

А между тем идеи для развития «Клюквы» есть.

Начнем от более реалистичных и наименее затратных до сложных, но перспективных:

1. сделать UI в браузере

2. написать расширение для IDE

3. включить сервис в систему CI/CD

4. разработать способ добавления бизнес информации в код проекта, чтобы в дальнейшем его можно было использовать для визуализации диаграмм бизнес процессов и генерации документации

Если вам лично или вашей компании будет интересно решить какую‑нибудь из этих задач, буду рад помочь и поучаствовать.

Если у вас есть идеи или предложения — пишите fomenko_ai@proton.me, обсудим.

Благодарю за внимание!