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С. 30 мая - 1 июня 2024 г. Санкт-Петербург, отель Cosmos Saint-Petersburg Pribaltiyskaya Hotel, ул. Кораблестроителей 14

50000 руб.

27.05.2023    22440    666    0    

307

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

Набор инструментов программиста и специалиста 1С для всех конфигураций на управляемых формах. В состав входят инструменты: Консоль запросов, Консоль СКД, Консоль кода, Редактор объекта, Анализ прав доступа, Метаданные, Поиск ссылок, Сравнение объектов, Все функции, Подписки на события и др. Редактор запросов и кода с раскраской и контекстной подсказкой. Доработанный конструктор запросов тонкого клиента. Продукт хорошо оптимизирован и обладает самым широким функционалом среди всех инструментов, представленных на рынке.

10000 руб.

02.09.2020    140983    774    391    

803

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

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

18000 руб.

06.10.2023    11638    31    6    

61

Инструментарий разработчика Программист Платформа 1С v8.3 Конфигурации 1cv8 Платные (руб)

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

5400 руб.

17.05.2024    14157    35    27    

78

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

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

10000 руб.

10.11.2023    7334    27    4    

51

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

Готовые тестовые сценарии, предназначенные для регресс-тестирования функционала конфигурации после обновления типовым релизом. Сценарии проверяют интерактивное заполнение форм документов, справочников и результат проведения документов. Сценарии возможно использовать как для vanessa-automation, так и для СППР. Поддерживаемые версии конфигураций ERP2 и КА2: 2.5.16.115.

2220 руб.

04.07.2022    7614    38    1    

25

SALE! %

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

Универсальный инструмент программиста для администрирования конфигураций. Сборник наиболее часто используемых обработок под единым интерфейсом.

3600 2880 руб.

14.01.2013    182015    1104    0    

876

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

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

9000 руб.

20.06.2023    17480    2    3    

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

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