Формирование и актуализация Markdown-исходников документации

Формирование структуры и содержимого документации осуществляется следующим образом:

• создание (редактирование) файлов расширения Markdown, являющихся отдельным документом с соответствующих определённой главе или подразделу;
• распределение .md файлов в файловой структуре согласно иерархии.

Создание оглавления

Файл SUMMARY.md - необходим для формирования заголовков документации, их последовательности и иерархии.

Файл является неотъемлемой частью документации и должен находиться только в корне проекта.

Форматирование файла-оглавления должно осуществляться согласно правилам, описанным ниже.

Любое отклонение от правил форматирования приведёт к игнорированию внесённых изменений или может вызвать ошибку при создании структуры документа.

Оглавление, описанное в SUMMARY.md состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе.

Элементы оглавления в SUMMARY.md

Пример оглавления в SUMMARY.md может выглядеть следующим образом:

[Общая информация]()

# Глава 1
- [Назначение и общие сведения]()
  - [Общие приёмы работы]()
  - [Общий порядок работы]()

---

# Глава 2
- [Описание работы и синтаксиса скриптов]()
  - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
  - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
  - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
  - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
  - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциии.md)
  - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция mdBook](readme.md)

Страница с документацией с данным оглавлением будет иметь следующий вид:

18

Основной структурной единицей оглавления являются ссылки Ссылки состоят из:

названия главы (подраздела) - в квадратных скобках пути к файлу, соответствующему содержимому раздела, формата markdown, относительно корневой папки проекта со всей документацией - в круглых скобках Важно: при при создании ссылок в пути к файлу необходимо использовать прямой слэш /. Это необходимо для корректного отображения страницы в документации.

Элементы, которые используются при создании оглавлений:

• Ненумерованные главы
• Ненумерованный заголовок первого уровня
• Нумерованный заголовок
• Глава-черновик
• Разделитель

Ненумерованные главы

В SUMMARY.md таким главам соответствует ссылка без знака - и табуляции

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

Такие главы не будут пронумерованы. Это полезно для предисловий, вступлений и т. д.

На такие главы существуют ограничения:

• префиксные главы не могут быть вложенными;
• все они должны быть на корневом уровне.
• не получится добавить префиксные главы после добавления пронумерованных глав.

Суффиксная глава - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав.

Ненумерованный заголовок первого уровня

В SUMMARY.md таким заголовкам соответствует текст с одним знаком # в начале.

Заголовки уровня 1 можно использовать в качестве заголовка для следующих пронумерованных глав. Это можно использовать для логического разделения различных разделов документа. Заголовок отображается как некликабельный текст. Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо. Заголовки частей должны быть заголовками h1 (один #), другие уровни заголовков игнорируются.

Нумерованный заголовок

В SUMMARY.md таким главам соответствует ссылка со знаком -

Нумерованные главы описывают основное содержание документа и могут быть вложенными, что позволяет создать необходимую иерархию (главы, подглавы и т. д.). Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция

Глава-черновик

В SUMMARY.md таким главам соответствует ссылка с пустым путём к файлу с описанием

Главы-черновики - это главы без файла и, следовательно, контента. Обычно используются разметки структуры документа, когда отсутствует содержание глав. Такие главы отображаются как неактивные ссылки в оглавлении. Главы-черновики пишутся как обычные главы, но без записи пути к файлу

Разделитель

Разделитель добавляет полосу, отделяющую одну часть оглавления от другой Разделитель - это строка, содержащая три и более тире: ---

Файловая структура при документировании

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

Файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления Для каждого раздела создаётся директория; для корневых разделов директории с описанием находятся в корне проекта src Если раздел содержит подразделы, создаются поддиректории внутри раздела В директории каждого раздела находятся файл с расширением .md, с документацией соответствующей главы Названия всех папок и файлов должны быть без пробелов Если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка assets, в которой размещаются файлы изображений Изображения именуются как asset_1, asset_2, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся Ниже приведён пример оглавления в SUMMARY.md и соответствующая ему файловая структура

Оглавление в SUMMARY.md:

[Общая информация]()

# Глава 1
- [Назначение и общие сведения]()
    - [Общие приёмы работы]()
    - [Общий порядок работы]()

---

# Глава 2
- [Описание работы и синтаксиса скриптов](Описание_работы_и_синтаксиса_скриптов/Описание_работы_и_синтаксиса_скриптов.md)
  - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
  - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
  - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
  - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
  - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциию.md)
  - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция по документированию](readme.md)

Файловая структура:

19

Работа с Markdown файлами

При написании документации в markdown редактировать содержимое можно либо вручную, либо через графический интерфейс VSCode

Для "ручного" редактирования - инструкция по использованию markdown: https://gist.github.com/Jekins/2bf2d0638163f1294637

Для редактирования через интерфейс VSCode можно использовать как стандартный функционал, так и расширения

Использование стандартного функционала:

Выделить текст и нажать по нему ПКМ Нажать "Рефакторинг" Выбрать необходимую функцию из появившегося списка или "Дополнительно" Через расширение EasyMarkdown:

установить расширение выделить редактируемый текст нажать на одну из кнопок редактирования текста в правом верхнем углу окна просмотра документа