ReactDoc — первое open source решение программы «Единая фронтальная система»

в 11:16, , рубрики: javascript, JS, open source, ReactJS, Блог компании Программа «Единая фронтальная система», Сбербанк, Сбертех

Программисты всегда пользовались генераторами документации, когда это было возможно. Это упрощает документирование, позволяет получить справку по продукту без обращения к коду самого проекта. В Программе долгое время использовался JavaDoc, т.к. большинство проектов написаны на Java, но это было до недавнего времени. Сейчас проекты развиваются  - мало кто представляет хороший продукт без хорошего UI. Отрасль frontend дала жизнь новому направлению разработки — разработчик UI. Концентрируясь на удобстве пользователя, а не на бизнес-процессах, UI-разработка позволяет избегать  сложности бизнес-приложений — камень преткновения многих enterprise-решений.

image

У Java разработчиков есть JavaDoc, а что есть у разработчиков UI?

Долгое время в этой сфере не было достойных инструментов, поскольку сложно подвергнуть автоматизации то, что не систематизировано. Со временем, появился инструмент, аналогичный JavaDoc, который даже получил схожее название — JSDoc. К его ключевым недостаткам можно отнести то, что он заставлял писать код определенным образом, что не всегда подходит для конкретного проекта. Стоит отметить, что код раздувался из-за обилия комментариев, что снижало читабельность самого кода для команды разработки.

Все изменилось в UI-разработке с приходом React. Все интерфейсы стали делиться на атомарные кусочки, из которых стали собираться огромные приложения: каждый кусок изолирован и покрыт необходимым тестами. Каждая компания имеет свою собственную библиотеку UI компонентов, которые среди разработчиков еще называют UIKit.

В программе «Единая фронтальная система» мы разработали свою библиотеку, однако, и ее необходимо было документировать.

Мы начали писать документацию, но быстро пришли к пониманию того, что готовить ее вручную очень трудозатратно. Мы теряем драгоценное время на документировании, при этом отстаём в развитии самого проекта. Родилась идея генерировать документацию прямо из кода, идея не нова, но мы решились попробовать. У нас был проект на React и TypeScript. Используя слабо документированные возможности TypeScript, мы начали делать свою генерацию для каждого компонента. Все комментарии к каждому свойству компонента становились кусочками той документации, которая выводилась.

Как этого удалось достичь?

Мы не стали погружаться глубоко в корни TypeScript — это заняло бы слишком много времени. Использовав typedoc,  получили структуру проекта в виде json, по этой структуре мы зеркально выстраиваем проект, но уже зная описания самих компонентов. Для удобной подгрузки описаний в саму документацию, мы реализовали особый компонент, который из зеркалированной структуры «вытягивает» описание и отображает его на странице. Звучит сложно, но на практике это работает как часы.

Дальше – больше. Нам не хотелось копировать код, чтобы вывести пример в документации и отобразить текст кода, на котором он был написан. Мы сделали отдельный компонент, который выводил и пример и код этого примера. Используя зеркалированную структуру,  нам удалось достичь связи примеров с их исходным кодом.

Мы разместили решение  на крупнейшем портале совместной разработки GitHub, чтобы вы могли использовать наш инструмент в своей ежедневной работе. Будем рады пообщаться в комментариях к посту.

Мы продолжаем работать над усовершенствованием решения, а именно:

  • Созданием live reloading: больше не нужно будет ждать пересборки всей библиотеки, чтобы увидеть результат в документации.

  • Поддержкой JavaScript: мы понимаем, что сейчас многие проекты не используют TypeScript в своих проектах.

  • Обновлением дизайна: сейчас инструмент выглядит аскетично, но это наши первые шаги в open source, обещаем, мы исправимся!

Автор:

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js