Документация — одна из самых важных составляющих любого проекта, особенно если этот проект с открытым кодом, который будут читать другие люди. Чтобы сделать мир opensource чуточку лучше, я попытался собрать свои знания в области организации модулей nodejs проектов и сделать такой инструмент как Makedoc!. Ремарка для адептов ruby: это почти то же, что и rdoc.info для руби.
Этот инструмент анализирует код проекта, выделяет потенциально документируемые куски кода (не важно, с документацией или без), и генерирует статический набор страничек, описывающих проект.
В кратце шаблон использования такой: идем на jsdoc.info/[githubusername]/[projectname] и видим готовую документацию по проекту. Либо идем на jsdoc.info/[githubusername] и получаем список проектов для которых можно сгенерировать документацию.
За деталями реализации прошу под кат.
Для начала, вот как это выглядит:
jsdoc.info/visionmedia/express
jsdoc.info/jaredhanson/passport
jsdoc.info/1602/express-on-railway
jsdoc.info/1602/jugglingdb
За анализ кода отвечает модуль makedoc. Этот модуль можно использовать как отдельный инструмент, если ваш проект не хостится на гитхабе в открытом доступе. Makedoc разбирает файлы в поисках трех основных семантических единиц: методов класса, методов экземпляра и просто методов. Также каждый файл определяется либо как Class-файл (содержит описание класса), либо как Module-файл (содержит экспорт функций).
В качестве рекомендуемого формата для документации выступает jsdoc. Однако, разбирается он не строго. Полная поддержка будет по мере развития проекта. Итак, если удается найти документацию для метода, она парсится при помощи markdown, а метод помечается как «задокументированный». В результате имеем такую метрику как «Docs coverage» — отношение числа строк покрытых документацией к числу недокументированных строк. В качестве последней цифры берется не общее число строк проекта, а только строки в методах, так что цифра в 100% достижима.
Проект работает на хостинге в 100mb RAM, с узким каналом и маленьким диском, поэтому чтобы все работало быстро проект не клонируется на жесткий диск, скачиваются только необходимые файлы, html разбирается при помощи jsdom + jquery. Первоначально была версия с клонированием репозитория, которая работала сильно медленнее и ничуть не лучше. Поэтому ограничиваемся исходниками в директории ./lib и не далее второго уровня вложенности (покрывает 90% проверенных проектов).
RailwayJS отрабатывает «пропущенные» статической middleware запросы и отправляет генерироваться документацию. В дальнейшем запросы отдаются статикой.
Проекту от роду неделя, поэтому пока реализован абсолютный минимум который можно показать. В планах развивать и улучшать парсер, чтобы поддержать как можно больше проектов. Следующий приоритет: автоматизация процесса генерации. Уже сейчас можно отправить POST запрос на /user/repo/update и обновить документацию, используя POST-receive hook на github. Только вот кто же будет это настраивать? Должно быть как в travis-ci: один тумблер и готово.
Пока запросы на генерацию разнесены во времени, все работает без нареканий, потому что статика отдается быстро, а разбор не требует больших ресурсов. Однако, если проект «полетит» и будет востребован, потребуется более серьезное железо. Поэтому прошу отнестить лояльно к возможному хабр-эффекту.
В настоящий момент очень нужен фидбэк от владельцев проектов, заинтересованных в использовании ресурса. Выбирать направление развития проекта ориентированного на community лучше всего совместно с активными участниками этого community, коих я хочу найти на хабре.
PS: для найденных проблем на сайте создаем issues тут: github.com/1602/railway-jsdoc-generator/issues
о проблемах с генератором документации пишем сюда: github.com/1602/makedoc/issues
Этот инструмент анализирует код проекта, выделяет потенциально документируемые куски кода (не важно, с документацией или без), и генерирует статический набор страничек, описывающих проект.
В кратце шаблон использования такой: идем на jsdoc.info/[githubusername]/[projectname] и видим готовую документацию по проекту. Либо идем на jsdoc.info/[githubusername] и получаем список проектов для которых можно сгенерировать документацию.
За деталями реализации прошу под кат.
Для начала, вот как это выглядит:
jsdoc.info/visionmedia/express
jsdoc.info/jaredhanson/passport
jsdoc.info/1602/express-on-railway
jsdoc.info/1602/jugglingdb
Как это работает
Makedoc
За анализ кода отвечает модуль makedoc. Этот модуль можно использовать как отдельный инструмент, если ваш проект не хостится на гитхабе в открытом доступе. Makedoc разбирает файлы в поисках трех основных семантических единиц: методов класса, методов экземпляра и просто методов. Также каждый файл определяется либо как Class-файл (содержит описание класса), либо как Module-файл (содержит экспорт функций).
JSDoc
В качестве рекомендуемого формата для документации выступает jsdoc. Однако, разбирается он не строго. Полная поддержка будет по мере развития проекта. Итак, если удается найти документацию для метода, она парсится при помощи markdown, а метод помечается как «задокументированный». В результате имеем такую метрику как «Docs coverage» — отношение числа строк покрытых документацией к числу недокументированных строк. В качестве последней цифры берется не общее число строк проекта, а только строки в методах, так что цифра в 100% достижима.
Tech stack: nodejs, railwayjs, bootstrap, jsdom, jquery
Проект работает на хостинге в 100mb RAM, с узким каналом и маленьким диском, поэтому чтобы все работало быстро проект не клонируется на жесткий диск, скачиваются только необходимые файлы, html разбирается при помощи jsdom + jquery. Первоначально была версия с клонированием репозитория, которая работала сильно медленнее и ничуть не лучше. Поэтому ограничиваемся исходниками в директории ./lib и не далее второго уровня вложенности (покрывает 90% проверенных проектов).
RailwayJS отрабатывает «пропущенные» статической middleware запросы и отправляет генерироваться документацию. В дальнейшем запросы отдаются статикой.
Планы
Проекту от роду неделя, поэтому пока реализован абсолютный минимум который можно показать. В планах развивать и улучшать парсер, чтобы поддержать как можно больше проектов. Следующий приоритет: автоматизация процесса генерации. Уже сейчас можно отправить POST запрос на /user/repo/update и обновить документацию, используя POST-receive hook на github. Только вот кто же будет это настраивать? Должно быть как в travis-ci: один тумблер и готово.
Пока запросы на генерацию разнесены во времени, все работает без нареканий, потому что статика отдается быстро, а разбор не требует больших ресурсов. Однако, если проект «полетит» и будет востребован, потребуется более серьезное железо. Поэтому прошу отнестить лояльно к возможному хабр-эффекту.
В настоящий момент очень нужен фидбэк от владельцев проектов, заинтересованных в использовании ресурса. Выбирать направление развития проекта ориентированного на community лучше всего совместно с активными участниками этого community, коих я хочу найти на хабре.
Спасибо!
PS: для найденных проблем на сайте создаем issues тут: github.com/1602/railway-jsdoc-generator/issues
о проблемах с генератором документации пишем сюда: github.com/1602/makedoc/issues
