RepoRadar Sourcey: генерация статических сайтов документации на основе OpenAPI и Markdown
Sourcey — это инструмент для создания статических сайтов документации на основе OpenAPI, Doxygen, MCP и Markdown. Он позволяет собрать все материалы в одном месте — справку, руководства и даже дорожные карты — без необходимости в дополнительных API или динамическом рендеринге.
Основная задача Sourcey — предоставить разработчикам полный контроль над документацией. Все генерируется на этапе сборки, что устраняет зависимость от сервера и упрощает развертывание. Отличается от аналогичных решений, таких как MkDocs или Swagger UI, тем, что не требует настройки серверов и не вызывает лишних задержек при доступе к документации. Идеально подойдет для команд, которые хотят быстро создать и развернуть документацию к своему API.
Проект написан на JavaScript и его можно запустить с помощью команды npx sourcey init. Учти, что Sourcey требует Node.js для работы, и не подходит для динамической генерации документации в реальном времени.
Проект Sourcey представляет собой инструмент, который позволяет создавать статические HTML-сайты для документации, комбинируя различные источники, такие как OpenAPI, MCP, Doxygen, godoc, rustdoc и Markdown. Это означает, что ты можешь собрать всю свою документацию, включая справочные материалы, руководства, журналы изменений и дорожные карты, в одном месте и размещать её на любом сервере.
Одной из ключевых особенностей Sourcey является то, что весь контент рендерится во время сборки, что исключает необходимость в дашбордах, API-запросах и других зависимостях во время выполнения. Это позволяет разрабатывать и развертывать документированные API-структуры без лишних заморочек.
Установка и запуск
Для установки Sourcey у тебя есть несколько опций:
- Используя npm:
npm install -g sourcey - Для macOS / Linux через Homebrew:
brew tap sourcey/tap && brew install sourcey - С помощью Docker:
docker run -v "$PWD":/docs sourcey/sourcey - Через Nix:
nix run github:sourcey/sourcey
После установки ты можешь инициализировать новый проект с помощью команды:
npx sourcey initЗатем, чтобы запустить сервер для разработки с поддержкой горячей перезагрузки, используй:
sourcey devДля сборки статического HTML просто запусти:
sourcey buildФункциональные возможности
Sourcey поддерживает обширные возможности, включая:
- Полное покрытие спецификаций OpenAPI (версии 2.0 и 3.0-3.2): рендеринг операций, схем и автогенерация примеров кода на 10 языках.
- Документацию для MCP с примерами кода на TypeScript и Python.
- Импорт существующих проектов с помощью MkDocs без необходимости ручного копирования.
- Поддержку документации C++ и Doxygen, а также Go и Rust без дополнительных зависимостей.
- Возможность настроить внешние темы и компоненты для создания удобного пользовательского интерфейса документации.
Ограничения
Несмотря на обширные возможности, у Sourcey могут быть некоторые ограничения:
- Нужен Node.js версии 20 или выше для работы с пакетом.
- Некоторые функции могут требовать определённых версий инструментов для поиска, таких как Rust и Go.
- Проект имеет лицензию AGPL-3.0, что может ограничить использование в коммерческих целях без открытия исходников.
Вывод
Sourcey — это мощный инструмент для создания документации, который поддерживает множество форматов и подходит для различных сценариев. У него простая установка и гибкие возможности настройки, однако стоит обращать внимание на лицензионные ограничения и требования к окружению для работы проекта.
Открыть на GitHub: sourcey/sourcey →
