Онлайн генератор документации для Node.JS проектов

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

    Комментарии 34

      +2
      Очень рад появлению вашего проекта.

      Большое спасибо. Как только в markdown-js внедрят поддержку GFM, начну использовать!
        0
        Можно им помочь внедрить GFM, действительно нужная фича ;)
          +1
          Завтра интегрирую работу @gjtorikian и отправлю PRq (см. github.com/evilstreak/markdown-js/issues/41).
            +1
            пока пробую этот форк: github.com/isaacs/github-flavored-markdown
            работает ок
              +1
              Блина, я уже начал править markdown-js. Спасибо за ссылку, тоже на него перейду :)
          0
          Что означает сокращение GFM?
          • НЛО прилетело и опубликовало эту надпись здесь
              +1
                0
                github.com/isaacs/github-flavored-markdown

                npm install github-flavored-markdown

                попробовал заинтрегрировать — выглядит неплохо, надо проверить на большем числе проектов, может на него и перейдем.
                  0
                  Жаль пулл-реквест висит год без комментов.

                  P.S. Это я так пессимизирую на тему социальности гитхаба :)
          • НЛО прилетело и опубликовало эту надпись здесь
              0
              js
              • НЛО прилетело и опубликовало эту надпись здесь
                  0
                  Как насчет такого преимущества, что документации может и не быть для того, чтобы проект был успешно распарсен? В этом случае может быть получена оценка покрытия документацией — цифра которая должна прибавить мотивации документировать проект.

                  Ну и в догонку, хоть я и не использовал Doxygen, зайдя на их сайт понял что не так-то просто будет это сделать. А тут идея такая, что лишних телодвижений не надо — один GET, и получи документацию.
                  • НЛО прилетело и опубликовало эту надпись здесь
              0
              Всё хорошо, только вот разработчиков на нод не сыщешь. Коммунити вокруг этого ф-ка действительно не хватает.
                +1
                Комьюнити есть! Твиттер, гуглогруппы и гитхаб довольно активны. Сказать по правде, я ожидал большего хабр-эффекта. После ретвита @tjholowaychuk гугланалитикс показывал под сотню посетителей единовременно, а сейчас — макс 20. Видимо тема nodejs не сильно популярна среди хабражителей :)

                Но на гитхабе и в группах приходится общаться много, и надо отдать должное комьюнити — в основном разработчики очень отзывчивы.
                  0
                  Этот инструмент можно использовать не только для документирования Node.js проектов.
                    +1
                    Да ладно? Может, условия вакансии не ахти? Есть, кстати, неплохая группа в Facebook, — MoscowJS.
                      0
                      Условия нормальные. Большинство задает вопрос: «А че это?». А разработка под мобильные еще больше сужает круг поиска. За ссылку спс, пошукаем. Мб еще есть какие ресурсы? Желательно на русском.
                        0
                        Значит нужно не искать готовое, а вкладывать. Просто так хорошие разработчики не появляются даже на перспективных направлениях. Разработчики находят место, где им будет комфортно и будет удобно учиться, и не часто его меняют.
                          0
                          Полностью согласен. Но в моем случае при поиске на удаленку в интересный проект с хорошей оплатой даже вариантов нет. Может быть не там ищу просто) Ладно, не будем оффтопить.
                            +1
                            А хорошая оплата — это сколько?
                              –1
                              Оплата сдельная, есть ТЗ. Если интересно, могу скинуть.
                    0
                    Раньше использовал jsdoc-toolkit
                      +1
                      Планируете ли вы использовать этот генератор для других языков?
                        0
                        А зачем? Для Ruby естественен YARD или Tomdoc.

                        Другое дело, что нужна поддержка C extensions.
                          0
                          Да, я в основном о них.

                          Думаю вы помните историю со взлётом Dox и знаете чем он закончил в итоге. Так что продолжаю вынашивать эту мысль.

                          P.S. На самом деле, думаю что можно организовать всё это дело так, чтобы можно было поддерживать любой язык. Тем более что кроме расширений есть ещё и кофескрипт.
                            0
                            Можно попробовать расширить для C, в принципе, не знаю только, есть ли смысл. Думаю, пока надо добиваться лучшего результата для js, а там видно будет.
                              0
                              А что за история с dox? Раньше оно вроде как html отдавало, а теперь только json. Это видимо отголоски тех событий?
                          • НЛО прилетело и опубликовало эту надпись здесь
                            0
                            Кстати, если генератор станет умнее, возможно стоит попробовать объединиться с startic.kr/njs, авто как раз планирует делать генерацию документации там.
                              0
                              Поумнеть генератору поможет фидбэк в виде проектов на которых в настоящий момент не очень адекватный результат. К сожалению не все в моих силах. Например, в случае с backbone.js может справиться только docco, потому что там такая архитектура файла.

                              Кстати, проект переехал на jsdoc.info
                                0
                                С поддержкой C/C++ я поколдую на днях, уже повесил себе тикет. И хотелось бы чуть большей настраиваемости, чтобы не только lib подсвечивать. Я тогда эти мысли на гитхабе уже изложу, а не здесь.

                            Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                            Самое читаемое