Приветствую, уважаемые форумчане!
На больших проектах, по разработке на платформе Terrasoft, ощущается острая необходимость документации кода. На сегодняшний день есть множество frameworks для автоматической генерации документов на основе markdown или wiki.
В связи с чем хотелось бы поднять обсуждение - найти оптимальное решение для документации кода конфигурации. Дабы не теряться в понятиях предлагаю начать с документации клиентской части.
Может кто-то использует нечто подобное, подскажите best-practice, поделитесь как вы решаете эту проблему.
Для генерации документации, клиентской части ядра, платформы, используется JSDuck. Можно сформировать для каждого сайта нечто а-ля https://academy.terrasoft.ru/jscoresdk/ Но как-бы заставить jsduck собирать информацию ещё и про схемы конфигурации... Или же проще использовать другой framework для этой задачи...
Нравится
Добрый день.
JSDuck является оптимальным решением и позволяет генерировать действительно удобную и полезную документацию. Приложения, созданные на ExtJS, поддерживают автоматическое создание документации, так как генератор изначально создавался для Sencha и позволяет распознавать синтаксис ExtJS.
Запуск генератора осуществляется из командной строки:
$ jsduck
При этом, вся конфигурация должна быть описана по умолчанию в файле jsduck.json, находящемся в этой же директории.
Можно все параметры конфигурации описывать в командной строке, не используя файл конфигурации. Например
$ jsduck path/to/src --output docs
Но я не рекомендую этого делать, если у вас очень много параметров конфигурации. Это очень не удобно и не наглядно.
Также можно указать другой путь к файлу конфигурации, если в этом есть необходимость. Например
$ jsduck --config=mypath/to/myconfig.json
Справку по всем параметрам командной строки можно посмотреть командой
$ jsduck --help
Все параметры могут быть использованы как из командной строки, так и в файле конфигурации.
Пример файла конфигурации:
{
"--title": "My Application Docs",
"--warnings": [
"-all:path/to/extjs/src"
],
"--output": "docs",
"--": [
"path/to/extjs/src",
"path/to/my/app"
]
}
Краткое описание параметров:
title — титульный заголовок на странице документации.
warnings — позволяет управлять потоком предупреждений, которые пишутся в консоль, если документированный код не соответствует самому коду. В приведенном примере с помощью опции "-all" игнорируются все предупреждения, возникающие в фреймворке extjs.
output — директория сгенерированной документации.
В последней секции "--" перечисляются директории с исходниками, из которых должна быть сгенерированна документация.
Ознакомиться с официальной документацией можно по этой ссылке: https://github.com/senchalabs/jsduck/wiki
Я читал документацию по JSDuck. И формировал документацию для ядра Terrasoft BPMonline.
Но как это поможет сгенерировать документацию для модулей конфигурации? Возможно ли настроить JSDuck так, чтобы можно было сгенерировать документацию по всем клиентским файлам конфигурации. Если у вас это удавалось - будет здорово, если вы со всеми поделитесь инструкцией и конфигами.
"Возможно ли настроить JSDuck так, чтобы можно было сгенерировать документацию по всем клиентским файлам конфигурации" - да, возможно. Если Вы читали документацию по JSDuck и формировали документацию для ядра Terrasoft BPMonline, ты Вы, безусловно, в курсе, что путь к исходным файлам, для которых необходимо сформировать документацию, указывается в файле конфигурации, примерно вот так:
"--": [
"path/to/extjs/src",
"path/to/my/app"
]
Готовой инструкции о том, как сформировать документацию для клиентских схем конфигурации у нас, к сожалению, нет. Процесс формирования документации довольно трудоемкий, для этого необходимо править комментарии в клиентских схемах конфигурации, для того чтобы парсер JSDuck мог работать корректно.
Привожу в качестве примера наш конфигурационный файл:
{
"--title": "bpm'online NUI Docs",
"--warnings": ["-link", "-nodoc(,)", "-inheritdoc", "-type_syntax"],
"--output": "..\\Documentation",
"--footer": "Terrasoft 2002-2016 Все права защищены",
"--tags": ".\\meta-tags.rb",
"--": [
"C:\\Projects\\NuewUnitTests\\Terrasoft.Nui\\ConfigurationJS"
]
}
Создание пользовательских тегов описано в документации JSDuck.
Добрый день! У меня наконец получилось извлечь боле менее вразумительную документацию с помощью JSDuck. Прошлый раз утилита постоянно обрывалась по ошибке. Я считал, что это из-за нестандартной структуры клиентских модулей. Нестандартных для классов ExtJS.
Но правильно настроив конфиг и используя правильные комментарии удалось сгенерировать кое-что полезное. Спасибо.
А как быть с серверным кодом? Может подскажите оптимальный инструмент для документации по серверному коду?
Добрый день!
К сожалению, на данный момент у нас нет опробованного оптимального инструмента для генерации документации по серверному коду Конфигурации Приложения. Идет анализ и тестирование подходящего инструмента. Рекомендую обратить внимание на следующие подходы к созданию документации и используемые при этом инструменты, описанные в статьях https://habrahabr.ru/post/102177/
и https://habrahabr.ru/post/252101/