Gostdown+

Это базовый шаблон для проекта на Gostdown+, который используется при разработке научных отчетов и документации в компании Инфорион. Построен на базе gostdown и demo-gostdown.

Стандартный проект состоит из:

• отчета (/report);
• документации (/docs_gost).

Стандартные возможности:

• версионный контроль;
• проверка правописания с Vale;
• собрать docx для отчета или документа из комплекта документации;
• собрать одностраничный HTML.

Дополнительные возможности: CI/CD (описано здесь).

Служебные файлы и скрипты хранятся в папках: .vscode (таски), scripts. Стили для проверки орфографии Vale хранятся в репозитории docus.

Требования

1. ОС Windows 10/11 (PowerShell 3 min), Microsoft Word 2019/2021/365.
2. Python >3.10
3. Git/Tortoise Git.
4. Pandoc, pandoc-crossref (версии 3.1 и сборка pandoc-crossref 3.1 confirmed).
5. VScode, Notepad++.
6. Extensions VSCode: Code Spell Checker, Russian - Code Spell Checker, Markdown all in one, markdownlint, mermaideditor/plantuml.
7. (Highly Recommended) Vale, Extension: Vale. Vale будет отлавливать жаргон, канцеляризмы и личные глаголы. В этом репозитории подключен простенький стиль и деактивированы два правила (см. vale.ini).

Для запуска скриптов PowerShell установите политики запуска Set-ExecutionPolicy Unrestricted/Set-ExecutionPolicy RemoteSigned (если работаете в доверенной сети) или отредактируйте скрипты для установки разрешений на уровне скриптов.

Старт нового проекта с шаблоном

1. Создать репозиторий для нового проекта и склонировать его на свою машину.
2. Поместить содержимое этой директории в корень репозитория (верхние папки /docs_gost,/report, scripts, в корне - vale.ini, .gitignore и т.д.).
3. Открыть папку в VScode. Установить нужные плагины, если они еще не установлены.
4. Настроить Vale.
5. Запустить таску Initialize project для создания директорий сборки (Terminal > Run Task > Initialize project).

Разработка документации

Документацию (например, по ГОСТ 19 или по какому вам нравится, можно даже вообще без ГОСТ) создаем в папке /docs_gost, на каждый документ -- отдельная папка. Для примера в /docs_gost есть папка example_doc с описанием новых фич Gostdown.

В преамбуле документа (как правило, 00_begin.md) можно задавать свои переменные, например, название ПО (soft-name). Использовать в тексте переменные нужно вот так: ${soft-name}.

В директории /docs_gost/single_source хранятся файлы, которые можно переиспользовать в документах. Например, если у нас есть 4 документа «Описание программы», которые отличаются незначительно, то можно общие куски вынести в отдельный файл и включать его несколько раз в разные документы. См. пример включения в файле /docs_gost/example_doc/01_main.md. Для включенных файлов также будут обрабатываться переменные.

См. подробнее описание фильтров, инклюдов и переменных здесь.

Отчет создается в папке /report, структура определяется требованиями ТЗ и объемом отчета.

Сборка документации

Операции сборки можно протестировать на этом шаблоне.

Сборка выполняется таской Build Doc, которая запускает сборку одного документа с нужными параметрами. Перед запуском сборки:

1. Убедиться, что в .vscode/tasks в блоке inputs.doc присутствует папка документа.

    "inputs": [
        {
            "id": "doc",
            "description": "Document Path: ",
            "type": "pickString",
            "options": [
                "example_doc",
                "dev1_guide_user" // example another doc
            ],
            "default": "example_doc"
        }
    ]

2. Открыть конфигурационный файл для свойств документа /scripts/configs/example_doc.xml. Название конфигурационного документа должно совпадать с папкой. В этом файле указываются значения полей в документе, которые будут обновлены. Здесь нужно указать название проекта, название документа, децимальный номер и т.д. Также можно создавать свои свойства (см. пример)

3. Открыть файл docx_include.txtв директории документа (/docs_gost/example_doc/docx_include.txt) и убедиться, что в файле перечислены все .md, которые вы хотите включить в .docx.

4. Запустить таску Terminal > Run Task > Build Doc.

5. В диалоге выбрать документ для сборки (например, example_doc).

6. В нижней части экрана откроется консоль с процессом сборки. Дождаться завершения операции (в списке консолей справа внизу для терминала появится галочка). Закрыть консоль.

   1. если на каком-то этапе процесс завис или завершился ошибкой, перед следующей попыткой необходимо завершить вручную процесс Microsoft Word в диспетчере процессов;

7. Собранный документ появится в папке build. Если папки build нет, скрипт упадет с ошибкой. Папка build создается при инициализации проекта.

8. Запустить таску Terminal > Run Task > Update Docx fields.

9. В диалоге выбрать документ для обновления полей (например, example_doc).

10. В нижней части окна запустится консоль с процессом обновления. Также дождаться завершения.

11. Документ в build будет обновлен значениями из /scripts/configs/example_doc.xml.

Примеры собранных документов доступны в example_build.

Сборка отчета

Пример структуры отчета представлен в report. Список собираемых документов также хранится в docx_include.txt.

Каждый раздел ТЗ - отдельная субдиректория, внутри каждой директории - _img. Это позволяет просматривать содержимое отчета в gitlab и vscode с картинками.

Чтобы отчет успешно собрался с картинками, нужно все картинки из _img из субдиректорий скопировать в корневую (поэтому важно не называть картинки одинаково для разных разделов). Это можно выполнить командами PowerShell или скриптом scripts/copy_img.py.

Для сборки отчета предоставляются две таски. Использовать можно обе с небольшими замечаниями:

1. Build Report (Without bat) -- команды PowerShell для копирования ресурсов в корень. Эта версия после сборки удаляет ВСЕ файл из report/_img, а также (из-за особенностей среды выполнения в VSCode) не записывает количество страниц, рисунков, таблиц и т.д. в реферате (если соберете оба варианта, поймете о чем я говорю). Это не критично, я все равно их руками редактирую.
2. Build Report Bat -- эта таска вызывает report/build.bat. Эта умная таска, которая копирует и удаляет только нужные картинки (ничего лишнего не удалит), а также корректно посчитает и вставит в нужные места счетчики для рисунков и таблиц в реферат.

Итак:

1. Убедиться, что в report/docx_include.txt есть все нужные для сборки файлы.
2. Запустить одну из тасок.
3. Результат будет сохранен в build.

Источники в формате BIB записываются в файл report/sources.bib. Ссылка на файл и стиль указана в преамбуле в report/begin.md. В тексте отчета ссылка на источник в формат [@cat1]. Список источников формируется автоматически (см. report/end.md).

Сборка одностраничного HTML

Эта бонусная возможность для сборки документа в одностраничный HTML. Собранные документы помещаются в build/web. При инициализации проекта туда уже распакованы необходимые для используемого шаблона js и css, так что веб-документ будет работать без Интернета.

В репозитории представлены шаблон easy_template, разработанный @ryangrose и версия easy_template_local с локальными ресурсами (этот шаблон будет работать без Интернета).

1. Убедиться, что в файле html_include.txt в директории документа есть все md, которые хотите включить в веб-версию. Иногда, список совпадает с docx_include, иногда нет.
2. Запустить задачу Make HTML. Выбрать документ и указать шаблон (можно запускать задачу с разными шаблонами, см. другие шаблоны в easy-pandoc-templates.
3. Скрипт соберет HTML и скопирует картинки из базовой директории (gost_docs/single_source/_img) и директории документа.

В получившемся HTML нужно поправить пути к картинкам, которые были в single_source. Для этого есть простой скрипт на PowerShell. Запустите задачу Fix image path in HTML, и скрипт scripts/command_to_fix_image_paths.ps1 заменит все ..\single_source\_img\ на _img/.

Credits

• Институт прикладной астрономии РАН, Дмитрий Павлов (ИПА РАН) и Алёна Водолагина (ИПА РАН), при участии Даниила Аксима (ИПА РАН), https://gitlab.iaaras.ru/iaaras/gostdown
• Институт прикладной астрономии РАН, Дмитрий Павлов, стилевой файл gost-r-7-0-5-2008-numeric-iaa.csl(CC BY-SA 3.0)
• @pandoc, фильтр include-files
• @cdivita, фильтр pandoc-curly-switch
• @ryangrose, шаблоны для pandoc easy-pandoc-templates
• @errata-ai, Vale