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

Программисты всегда пользовались генераторами документации, когда это было возможно. Это упрощает документирование, позволяет получить справку по продукту без обращения к коду самого проекта. В Программе долгое время использовался 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, обещаем, мы исправимся!

Комментарии (2)

  • 3 марта 2017 в 14:24

    0

    ↑

    ↓

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

    Неужели этого не было, в частности, в компонентах ExtJS или директивах AngularJS?

  • 3 марта 2017 в 14:44

    0

    ↑

    ↓

    Демку бы залили куда-нибудь.

© Habrahabr.ru