bsl2jsdoc - Генератор документации по файлам исходных текстов конфигурации (расширения) 1С: Предприятие 8.3

Проект на Gitlab

Тема betterdocs

Пример

Gitlab pages https://shmalevoz.gitlab.io/bsl2jsdoc по коду библиотеки общих методов

Требуемое оформление кода

Обрабатывается код общих модулей области #ПрограммныйИнтерфейс

Лидирующий непрерывный блок комментария в начале модуля служит его описанием

Предполагается стандартное оформление комментариев методов по стандарту вендора

строки с пустым комментарием считаются окончание блока в описании метода

шаблон:

// <Описание метода>
// 
// Параметры:
//    <Имя> - <Тип[, Тип, ...]> [- Описание параметра]
//    <Имя> - <Тип[, Тип, ...]> [- Описание параметра]
//
// Возвращаемое значение:
//    <Тип[, Тип, ...]> [- Описание возвращаемого значения]
//
// Пример:
//    Произвольный текст примера использования

пример:

// Сравнивает версии. Возвращает 
// -1 если Версия1 < Версия2
// 0 если Версия1 = Версия2
// 1 если Версия1 > Версия2
// 	При наличии статуса разработки в какой-либо версии и равенстве вышестоящих
// 	частей, версия со статусом разработки считается младшей
// 	Если часть строки версии содержит нечисловые символы, то они обрабатываются следующим образом
// 		любые символы < (alpha = a) < (beta = b) < rc < # < (pl = p)
// 	, нечисловые строки регистроНЕзависимы
//
// Параметры: 
// 	Версия1 - Строка - Cтрока версии 1
// 	Версия2 - Строка - Cтрока версии 2
//
// Возвращаемое значение:
//   Число
// 
// Пример:
// ВерсияСравнить("1", "1.0") = -1
// ВерсияСравнить("1.0", "1.01") = -1
// ВерсияСравнить("1.01", "1.1") = 0
// ВерсияСравнить("1", "1.10") = -1
// ВерсияСравнить("1.10", "1.10b") = 1
// ВерсияСравнить("1.10b", "1.10.0") = -1
//  
Функция ВерсииСравнить(Версия1, Версия2) Экспорт
  ...

Установка

Для формирования html документации требуется установленный nodejs

например, для Ubuntu

sudo apt install nodejs -y

Скрипт генерации документации и зависимости

git clone -b stable https://gitlab.com/shmalevoz/bsl2jsdoc.git
cd bsl2jsdoc
git submodule init
git submodule update --remote

Использование

bsl2jsdoc make --projectdir путь/корня/проекта --src подкаталог/проекта/исходных/кодов --dst подкаталог/документации/проекта

Команды

• make - объединение команд bsl2js и js2html
• bsl2js - формирует в каталоге dst/js jsdoc-совместимые файлы аннотаций по исходных кодам общих модулей конфигурации (расширения)
• js2html - формирует в каталоге dst/html окончательную документацию по файлам jsdoc аннотаций

Опции, обязательные

• --projectdir - базовый каталог проекта конфигурации (расширения) 1С
• --src - подкаталог проекта, содержащий исходные файлы. для команд bsl2js или make подкаталог проекта, содержащий выгрузку конфигурации, для команды js2html подкаталог файлов аннотаций jsdoc
• --dst - целевой подкаталог документации

Опции, необязательные

• --names-prefix - используемый для отбора объектов префикс имен. по-умолчанию для конфигурации пустой, для расширения префикс имен расширения

  • для конфигураций - если не задано, то общие модули, исключая содержащие знак подчеркивания; иначе общие модули, имеющие заданный префикс
  • для расширений - если не задано, то общие модули, содержащие префикс расширения; иначе общие модули, имеющие заданный префикс

• --template - имя используемой для рендеринга html темы документации. допустимы docdash (по-умолчанию), betterdocs
• --srcbaseurl - URL публикации исходных кодов конфигурации (расширения), например https://site/project/branche/src/config
• --disable-info - отключить вывод информационной строки, использовать для сборочных линий/неизвестных терминалов/в случае ошибки выполнения tput
• --man-prefix - префикс имен общих макетов, содержащих примеры использования (в markdown формате)
• --man-config - имя общего макета, содержащего настройки примеров использования (см. https://jsdoc.app/about-tutorials.html)
• --dedug - вывод отладочных сообщений
• --help - вывод справки по использованию

Линии сборки Gitlab/Github/...

Пример шага сборочной линии Gitlab.

Предполагается, что bsl2jsdoc объявлен в зависимостях проекта, например

git submodule add -b stable https://gitlab.com/shmalevoz/bsl2jsdoc.git depends/bsl2jsdoc

# предопределенное имя шага для публикации на pages.gitlab.io
pages:

  image: 
    name: node:latest

  #
  # Изменяемые переменные, заполнить путями проекта
  #
  variables:
    # подкаталог исходных кодов bsl (выгрузки конфигурации в файлы)
    SOURCES: "src/config"
    # целевой каталог генерируемой документации
    DESTINATION: "build/docs"
    # базовый адрес опубликованных исходных кодов bsl
    SRCBASEURL: "https://gitlab.com/{user}/{project}/-/tree/{branch}/{path}/{to}/{sources}"
    # префикс имен общих макетов руководств
    MANPREFIX: "ом_man"
    # имя общего макета с настройками руководств
    MANCONFIG: "ом_manconfig"
    # префикс имен общих макетов статичных файлов, имя файла в комментарии макета
    STATICPREFIX: "ом_stc"
  before_script:
    # bsl2jsdoc как зависимость проекта
    - cd "$CI_PROJECT_DIR"
    - git submodule init depends/bsl2jsdoc
    - git submodule update --remote depends/bsl2jsdoc
    # зависимости самого bsl2jsdoc
    - cd "$CI_PROJECT_DIR/depends/bsl2jsdoc"
    - git submodule init
    - git submodule update --remote
  script:
    # сборка документации
    - > 
      $CI_PROJECT_DIR/depends/bsl2jsdoc/bsl2jsdoc make 
      --disable-info 
      --projectdir $CI_PROJECT_DIR 
      --src "$SOURCES" 
      --dst "$DESTINATION" 
      --srcbaseurl "$SRCBASEURL"
      --man-prefix "$MANPREFIX" 
      --man-config "$MANCONFIG" 
      --static-prefix "$STATICPREFIX"
    # и ее перенос в каталог публикации
    - mv $CI_PROJECT_DIR/$DESTINATION/html $CI_PROJECT_DIR/public
  
  # сформированная документация как артефакт для pages
  artifacts:
    paths:
      - public

  # запуск шага только для тэгов (релизов)
  only:
    - tags
  except:
    - branches

Ограничения

• В описании модулей (ведущий блок комментария) markdown не работает, необходимо использовать прямые html вставки. Связано с тем, что в блоке описания выведены свойства модуля по метаданным и для форматирования использована прямая html разметка. Ограничение на использование markdown только для описания модулей

Подробности

Для построения домашней страницы документации используются

• Синоним, идентификатор, версия конфигурации (расширения) по метаданным
• Общий макет <префикс имен>README

Состав подсистем, общих модулей и их свойств заполняется по данными конфигурации (расширения).

Все описания трактуются как тексты в формате markdown, включено расширение merdaid

Для использования прочих шаблонов оформления документации необходимо использовать команду bsl2js. В каталоге $dst/js проекта будут сформированы файлы с jsdoc-совместимыми аннотациями, к ним применить любой шаблон оформления jsdoc (примерный список с демо-примерами)

В js документации используются нестандартные тэги @category и @subcategory, необходмиые для группировок темой betterdocs. При использовании собственных настроек jsdoc.json и/или других тем оформления добавить в jsdoc.json "allowUnknownTags": [ "category", "subcategory" ]

Рекомендуется указывать опцию --srcbaseurl, в таком случае будут сформированы ссылки на объявления методов в исходном коде модулей

Применяемые настройки шаблонов оформления

1. при наличии, из файла jsdoc.json базового каталога проекта
2. иначе применяются настройки по-умолчанию проекта шаблонов

Особенности используемых тем

• docdash - поиск происходит по именам как модулей, так и методов. группировка модулей в панели навигации отсутствует
• betterdocs - поиск только по именам модулей. есть трехуровневая группировка модулей по подсистемам в панели навигации

Внесенные в темы изменения

• изменена цветовая палитра
• увеличена ширина панелей навигации
• переведены на русский заголовки элементов
• удалено кодирование имен файлов в URI.