Методические указания по описанию паспортов моделей в ПК PRADIS и методика подготовки документации для применения автоматического генератора sphinx

Программный комплекс для автоматизации моделирования нестационарных процессов в механических системах и системах иной физической природы

Описание паспортов моделей ПК PRADIS

Для создания паспортов в PRADIS существуют различные объекты. Описания свойств этих объектов представлены в таблицах 1-11.

../../_images/Models_Passports_and_Documentation2.png

Рисунок 1. Объект описания Port

Таблица 1 - Свойства объекта описания Port - Описание узла

№

Имя

Значение по умолчанию

Описание

1

Name

Node

Имя узла

2

English

Описание на английском

3

L anguage2

Описание на языке 2

4

Type

DOF1

Тип узла [DOF1,Point,Point2d,XY,XYZ]
../../_images/Models_Passports_and_Documentation3.png

Рисунок 2. Объект описания Parameter

Таблица 2 - Свойства объекта описания Parameter - Описание параметра

№

Имя

Значение по умолчанию

Описание

1

Name

Имя параметра

2

English

Описание на английском

3

L anguage2

Описание на языке 2

4

Type

base.real

Тип параметра

5

Default

Значение по умолчанию
../../_images/Models_Passports_and_Documentation4.png

Рисунок 3. Объект описания ModelHeader

Таблица 3 - Свойства объекта описания ModelHeader - Описание заголовка модели

№

Имя

Значение по умолчанию

Описание

1

Name

Имя модели

2

Module

Имя модуля

3

Alias

Псевдоним модели

4

Image

Имя ПГО модели

5

English

Описание на английском

6

Language2

Описание на языке 2

7

Priority

5

Приоритет [1,2,3,4,5,6,7,8,9,10,11,12]

8

EXT

1

Число внешних степеней свободы

9

ENT

1

Число внутренних степеней свободы

1 0

PAR

0

Число параметров простого типа

1 1

VPR

None

Признак переменного числа параметров [None, Variable, Even, Odd]

1 2

ADR

Displacement

Ключ, относительно чего записан якобиан [Displacement, Velocity, Acceleration]

1 3

IGN

0

Ключ, какие элементы якобиана игнорировать [None, Velocity, Acceleration, VelocityAcceleration]

1 4

WRK

0

Число рабочих переменных

1 5

WRP

0

Сколько рабочих переменных соответствует каждому параметру

1 6

STR

0

Число переменных состояния

1 7

STP

0

Сколько переменных состояния соответствуют каждому параметру

1 8

NodeList

Список узлов

1 9

Par ameterList

Список параметров

2 0

WorkList

Список рабочих переменных

2 1

StateList

Список переменных состояния
../../_images/Models_Passports_and_Documentation5.png

Рисунок 4. Объект описания ObjectHeader

Таблица 4 - Свойства объекта описания ObjectHeader - Описание заголовка объекта

№

Имя

Значение по умолчанию

Описание

1

Name

Имя модели

2

Module

Имя модуля

3

Alias

Псевдоним модели

4

English

Описание на английском

5

Language2

Описание на языке 2

6

Priority

5

Приоритет [1,2,3,4,5,6,7,8,9,10,11,12]

7

NodeList

Список узлов

8

Par ameterList

Список параметров

9

FieldList

Список полей
../../_images/Models_Passports_and_Documentation6.png

Рисунок 5. Объект описания OVPHeader

Таблица 5 - Свойства объекта описания OVPHeader - Описание заголовка ПРВП

№

Имят

Значение по умолчанию

Описание

1

Name

Имя ПРВП

2

Module

Имя модуля

3

Alias

Псевдоним ПР ВП

4

English

Описание на английском

5

Language2

Описание на языке 2

6

Priority

5

Приоритет [1,2,3,4,5,6,7,8,9,10,11,12]

7

OUT

1

Число компонент ПРВП

8

SYS

1

Число передаваемых в ПРВП внутренних переменных свободы

9

VPS

None

Признак переменного числа внутренних переменных [None, Variable, Even, Odd]

10

PAR

0

Число параметров простого типа

11

VPR

None

Признак переменного числа параметров [None, Variable, Even, Odd]

12

WRK

0

Число рабочих переменных

13

WRP

0

Сколько рабочих переменных соответствует каждому параметру

14

WRS

0

Сколько рабочих переменных соответствует каждой внутренней переменной

15

NodeList

Список узлов

16

Par ameterList

Список параметров

17

WorkList

Список рабочих переменных
../../_images/Models_Passports_and_Documentation7.png

Рисунок 6. Объект описания ImageHeader

Таблица 6 - Свойства объекта описания ImageHeader - Описание заголовка ПГО

№

Имя

Значение по умолчанию

Описание

1

Name

Имя ПГО

2

Module

Имя модуля

3

Alias

Псевдоним ПГО

4

English

Описание на английском

5

Language2

Описание на языке 2

6

Priority

5

Приоритет [1,2,3,4,5,6,7,8,9,10,11,12]

7

EXT

1

Число степеней свободы

8

PAR

0

Число параметров простого типа

9

VPR

None

Признак переменного числа параметров [None, Variable, Even, Odd]

1 0

VPS

None

Признак переменного числа внутренних переменных [None, Variable, Even, Odd]

1 1

WRK

0

Число рабочих переменных

1 2

WRP

0

Сколько рабочих переменных соответствует каждому параметру

1 3

WRS

0

Сколько рабочих переменных соответствует каждой внутренней переменной

1 4

UNV

None

Признак связи ПГО с переменным числом внутренних переменных [No, Yes]

1 5

NodeList

Список узлов

1 6

Par ameterList

Список параметров
../../_images/Models_Passports_and_Documentation8.png

Рисунок 7. Объект описания ModuleHeader

Таблица 7 - Свойства объекта описания ModuleHeader - Описание заголовка модуля

№

Имя

Значение по умолчанию

Описание

1

Name

Имя модуля

2

English

Описание на английском

3

L anguage2

Описание на языке 2
../../_images/Models_Passports_and_Documentation9.png

Рисунок 8. Объект описания ParameterHeader

Таблица 8 - Свойства объекта описания ParameterHeader - Описание заголовка типа параметра

№

Имя

Значение по умолчанию

Описание

1

Name

Имя типа параметра

2

Module

Имя модуля

3

English

Описание на английском

4

L anguage2

Описание на языке 2

5

F ieldList

Список полей
../../_images/Models_Passports_and_Documentation10.png

Рисунок 9. Объект описания NodeHeader

Таблица 9 - Свойства объекта описания NodeHeader - Описание заголовка типа параметра

№

Имя

Значение по умолчанию

Описание

1

Name

Имя типа узла

2

Module

Имя модуля

3

English

Описание на английском

4

L anguage2

Описание на языке 2

5

F ieldList

Список полей
../../_images/Models_Passports_and_Documentation11.png

Рисунок 10. Объект описания Field

Таблица 10 - Свойства объекта описания Field - Описание поля

№

Имя

Значение по умолчанию

Описание

1

Name

Имя параметра

2

English

Описание на английском

3

L anguage2

Описание на языке 2

4

Type

base.real

Тип параметра
../../_images/Models_Passports_and_Documentation12.png

Рисунок 11. Объект описания SchemeGenerator

Таблица 11 - Свойства объекта описания SchemeGenerator - Генератор

№

Имя

Значение по умолчанию

Описание

1

Sc heme-File

Схема

2

I sDocument

yes

Флаг опции генерации документации [yes,no]

Разработка методики подготовки паспортов моделей

1. Рассмотрим создание паспорта модели на примере модели «Направляющие 2D, препятствующие вращению вокруг оси движения». Иконка представлена на Рисунок 12.

../../_images/Models_Passports_and_Documentation13.png

Рисунок 12. Иконка рассматриваемого элемента

Информацию о данном элементе берем из файла с расширением XML DINAMA\sysarm\XML\Links\Model\NPLV.xml, содержимое выглядит следующим образом (Рисунок 13)

../../_images/Models_Passports_and_Documentation14.png

Рисунок 13. Файл XML

2. В схему паспорта модели из модуля «Passport» каталога компонентов добавляем объекты описания: ModelHeader, Port, Parameter. (Рисунок 14.)

../../_images/Models_Passports_and_Documentation15.png

Рисунок 14. Добавление элементов описания

3. Заполняем параметры объектов описания: всю необходимую информацию берем из XML файла. Заполнение параметров для объекта Port с названием Body1 на Рисунок 15.

../../_images/Models_Passports_and_Documentation16.png

Рисунок 15. Заполнение параметров для объекта Port с названием Body1

4. После заполнения всех параметров нужно указать их в ModelHeader. (Рисунок 16)

../../_images/Models_Passports_and_Documentation17.png

Рисунок 16. Указание параметров в ModelHeader

5. Сохраняем схему NPLV.sch в директорию C:\project\Links\Model (Рисунок 17)

../../_images/Models_Passports_and_Documentation18.png

Рисунок 17. Сохранение схемы NPLV.sch

6. Сохраняем схему паспорта модели как xml паспорт путем применения встроенной в Qucs утилиты «Export as passport» (Рисунок 18.а). Необходимо создать новый фиктивный (пустой) xml файл в папке проекта. Название файла, который требуется создать, получается из названия схемы паспорта путем замены расширения с sch на xml, т.е. NPLV.xml. (Рисунок 18.б)

../../_images/Models_Passports_and_Documentation19.png
../../_images/Models_Passports_and_Documentation20.png

Рисунок 18. а) утилита «Export as passport», б) файл NPLV.xml

Обновление паспортов моделей на основе исходных текстов математических моделей

Представлены исходные тексты для 380 моделей. Из этих текстов выбраны данные для паспортов моделей.

Подготовлено 380 xml паспортов моделей для всех текущих модулей ПК PRADIS.

методика подготовки документации для применения автоматического генератора sphinx

Существует множество генераторов документации: Asciidoc, Doxygen, Sphinx. Для разработки общей документации был выбран Sphinx. Это генератор документации, который преобразует файлы в формате reStructuredText в HTML website и другие форматы.

reStructuredText (сокращение: ReST, расширение файла: .rst) — облегчённый язык разметки, который может быть преобразован в различные форматы — HTML, ePub, PDF и другие. Документы в формате .rst можно открывать и редактировать в любом простом текстовом редакторе (например, в Блокноте). Это позволяет работать над документацией в любых условиях, на любых платформах, без необходимости использовать специализированное программное обеспечение.

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

Отдельно хотелось бы отметить требования к синтаксису reStructuredText.

Основные концепции:

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

  • В командах (директивах) используется символ обратной кавычки «`». Использование обычных одинарных кавычек в командах не приведет к желаемым результатам.

  1. Заголовки

ReStructuredText поддерживает несколько уровней заголовков. Заголовки первого уровня (главы) подчеркиваются символом равно =. Заголовки второго уровня (подглавы) подчеркиваются символом короткого тире или минуса -. Заголовки третьего уровня (подпункта) подчеркиваются символом тильды ~. Для параграфов допускается использовать подчеркивание символами двойных кавычек “

  1. Абзацы в reStructuredText отделяются друг от друга пустой строкой

  2. Начертание

Чтобы выделить текст жирным начертанием или курсивным используется обособление звездочками:

**жирный текст**

*курсив текст*

Не допускается наличие пробелов между выделяемым словом и звездочкой

  1. Нумерованные списки создаются с помощью символа решетки с точкой #.

  2. Маркированные списки создаются с помощью символа звездочки * или дефиса -. Пробелы после маркера обязательны.

  3. `Вложенные списки

* Первый уровень

* Второй уровень

* Третий уровень

  1. Верхние и нижние индексы добавляются с помощью команд  :sub:  и :sup:

  • H\ 2\ O - H2O

  • E = mc\ 2` - E = mc:sup:`2

  1. Для вставки цитат используется отступ, сделанный с помощью клавиши Tab.

9) Можно оставлять комментарии, которые отображаются только в исходном файле ReST. Комментарии создаются с помощью двух точек в начале предложения .. . Для создания многострочных комментариев необходимо соблюдать отступ.

  1. Для примеров частей исходного кода (листинги) используется команда из двух двоеточий :: .

  2. `Автозамены (Подстановки)

Язык |ReST| — очень гибкий язык разметки (подстановки).

  1. Дата и время

  1. `Вставка текста из других файлов

14) Иногда возникает необходимость визуально отделить абзац, для этого можно воспользоваться чертой, достаточно поставить подряд несколько дефисов (не меньше 4-х), также можно воспользоваться нижним подчеркиванием. Символы черты должны быть отбиты пустыми строками до и после. Черта не должна завершать документ. Черта, расположенная в самом конце документа может вызывать ошибки при сборке.

  1. Внешние ссылки создаются так:

  1. Внешние ссылки выглядят так: ссылка_.

  1. Если несколько слов, тогда так:

  1. Более компактная запись ссылок

  1. Вставка изображения между слов |кубик-рубика| осуществляться с помощью функции автозамены:

Вставка изображений между абзацами осуществляется так:

pradis_tutorials/tutorial_2D_method/_static/favicon.png
scale:

300 %

align:

center

alt:

Альтернативный текст

Подпись изображения

Легенда изображения.

Параметр :scale: устанавливает масштаб изображений.

Параметр :align: устанавливает обтекание текстом, может принимать опции left, center или right.

  1. Содержание

На основе заголовков ReST автоматически создает оглавление, которое вставляется командой .. contents:

  1. `Блоки примечаний и предупреждений

Attention! - Блок Внимание, команда: .. attention:

Caution! - Блок Осторожно, команда: .. caution:

!DANGER! - Блок **Опасно**, команда: .. danger::

Error - Блок Ошибка, команда: .. error:

Hint - Блок Подсказка, команда: .. hint:

Important - Блок Важно, команда: .. important:

Note - Блок Примечание, команда: .. note:

Tip - Блок Совет, команда: .. tip:

Warning - Блок Предупреждение, команда: .. warning:

19) Вставка формул осуществляется командой .. math:: . Для ввода формул используется синтаксис LaTeX.

  1. Таблицы

команды ..``table::`` обязателен)

| Header row, column 1 | Header 2 | Header 3| Header 4|

+========================+============+==========+==========+

| body row 1, column 1 | column 2 | column 3| column 4|
| body row 2 | Cells may | span | columns.|
| body row 3 | Cells may | - Table | cells |
| body row 4 | - body | elements| |
../../_images/Models_Passports_and_Documentation21.png

Рисунок 19. Пример оформления таблицы

A B A

and B

False False False

True False False

False True False

True True True