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

25.10.22

Разработка - Инструментарий разработчика

Генератор документации по файлам исходных текстов конфигурации (расширения) 1С: Предприятие 8.3. Используются "стандартные" для 1С комментарии описания методов.

Проект на 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.

См. также

Инструментарий разработчика Роли и права Запросы СКД Программист Руководитель проекта Платформа 1С v8.3 Управляемые формы Запросы Система компоновки данных Платные (руб)

Инструменты для разработчиков 1С 8.3: Infostart Toolkit. Автоматизация и ускорение разработки на управляемых формах. Легкость работы с 1С.

15500 руб.

02.09.2020    172920    969    403    

928

Инструментарий разработчика Чистка данных Свертка базы Инструменты администратора БД Системный администратор Программист Руководитель проекта Платформа 1С v8.3 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х 1С:Управление нашей фирмой 3.0 Россия Платные (руб)

Инструмент представляет собой обработку для проведения свёртки или обрезки баз данных. Работает на ЛЮБЫХ конфигурациях (УТ, БП, ERP и т.д.). Поддерживаются серверные и файловые базы, управляемые и обычные формы. Может выполнять свертку сразу нескольких баз данных и выполнять их автоматически без непосредственного участия пользователя. Решение в Реестре отечественного ПО

8400 руб.

20.08.2024    15155    110    48    

108

Пакетная печать Печатные формы Инструментарий разработчика Программист Платформа 1С v8.3 Запросы 1С:Зарплата и кадры бюджетного учреждения 1С:ERP Управление предприятием 2 1С:Управление торговлей 11 Платные (руб)

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

22200 руб.

06.10.2023    17534    47    15    

77

Инструментарий разработчика Программист Платформа 1С v8.3 1C:Бухгалтерия Платные (руб)

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

9360 руб.

17.05.2024    27597    100    48    

141

Инструменты администратора БД Инструментарий разработчика Роли и права Программист Платформа 1С v8.3 1C:Бухгалтерия Россия Платные (руб)

Расширение позволяет без изменения кода конфигурации выполнять проверки при вводе данных, скрывать от пользователя недоступные ему данные, выполнять код в обработчиках. Не изменяет данные конфигурации, легко устанавливается практически на любую конфигурацию на управляемых формах.

15000 руб.

10.11.2023    12073    46    33    

67

DevOps для 1С DevOps и автоматизация разработки Программист Стажер Платные (руб)

Данный онлайн-курс (интенсив) предусматривает изучение процессов, инструментов и методик DevOps, их применение при разработке на платформе 1С. 

2500 руб.

20.06.2023    24167    20    4    

321

Тестирование QA DevOps и автоматизация разработки Программист Пользователь Платформа 1С v8.3 1С:Бухгалтерия 3.0 Россия Бухгалтерский учет Налоговый учет Платные (руб)

Автотесты 1С - готовые тестовые сценарии, предназначенные для регресс-тестирования функционала конфигурации после обновления типовым релизом. Сценарии проверяют интерактивное заполнение форм документов, справочников и результат проведения документов. Сценарий – feature-файл, разработанный с помощью vanessa-automation. Запуск сценария выполняется интерактивно с помощью vanessa-automation или с помощью vanessa-runner в CI-системах. Доступно тестирование тонкого клиента. Поддерживаемые версии конфигураций 1С:Бухгалтерия предприятие 3.0 и версии КОРП: 3.0.166.17.

2160 руб.

20.01.2022    8372    29    0    

14
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. charmillion 01.12.22 16:19 Сейчас в теме
Пример по адресу: https://shmalevoz.gitlab.io/bsl2jsdoc не открывается.

Работает только на общих модулях?
3. sandr13 35 03.12.22 17:34 Сейчас в теме
... ну и что получается в результате?
4. shmalevoz 309 03.12.22 21:59 Сейчас в теме
(1) На самом деле как оказалось gitlab.io заблокирован Роскомнадзором где-то в апреле. При использовании например прокси он открывается
Оставьте свое сообщение