Ранее, долгое время для создания документации к сводке методов (API) использовался typedoc, Это стандартный способ размещения деклараций TypeScript, быстро настраивается и работает из коробки.

Он был дополнен под наши нужды с помощью плагинов и расширения встроенной темы.

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

Все стало еще сложнее как только появилась потребность в добавлении библиотек. Мы пытались сделать несколько вещей — сконвертировать все декларации по отдельности для создания нескольких пакетов, использовать плагины для встроенной поддержки монореп и не только. Результаты не оправдали себя, копию этого варианта можно найти в отдельном репозитории. Было принято решение начать все с нуля. Ну или почти.

Попытки создать встроенную сводку методов принимались еще в далеком 2022, когда документация только-только начала свою разработку. Для корректной сборки деклараций было предпринято еще больше шагов, ведь документация могла быть сгенерирована только из ES6 модулей с экспортами. Наши же декларации требуют видимости в глобальном контексте и подобное не поддерживают. Пришлось повозиться.

Найти скриншоты было достаточно сложно, а вот коммит переезда на новую структуру можно посмотреть здесь.

Результат, честно говоря, даже сейчас выглядит довольно спорно. Да и от времени сборки на старом Docusaurus ничего не убавлялось, требовалось изменять количество выделяемой памяти. Сборка сайта занимала примерно (!) час реального времени, вместо пары минут. Сказать что результат не стоит того это не сказать ничего. 

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

Да. Но не спешите делать выводы, взгляните сразу на результат.

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

Страницы преобразовываются самим Docusaurus (движке, на котором построена вся документация целиком и полностью), уже привычно они состоят из индекса, сводки справа для быстрого перемещения и самой декларации. Описание методов приправлено новыми компонентами и тегами, все по канонам варианта из 2022, но куда разнообразнее.

Сигнатуры находятся внутри одного метода и перемещение между ними как никогда проще, можно кликать сразу по нужному типу для перехода к нему (раньше методы были разделены):

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

В этом описании можно увидеть новые карточки, они создаются из тегов @remarks, @example, @deprecated и @throws в ваших декларациях, это полноценные блоки для длинных и не очень описаний:

Моих декларациях? Да, теперь на сайте помимо деклараций для Core Engine представлены моды и библиотеки. Добавить их может абсолютно каждый, запросив пулл реквест для этой папки:

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

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

А пока разработка продолжается, протестировать новый подход к генерации API можно по публичному адресу. Старый вариант будет доступен еще какое-то время, но только при открытии через внешние ссылки (внутри документации тестируется переход по ссылкам в сводке методов). Что думаете, стало удобнее?