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

Формирование структуры и содержимого документации осуществляется следующим образом:
*создание (редактирование) файлов расширения <code>Markdown</code>, каждый из которых является отдельным документом и соответствует определённой главе или подразделу; 
*распределение <code>.md</code> файлов в файловой структуре согласно иерархии.

==Оглавление==

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

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

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

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

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

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

<syntaxhighlight lang="markdown">
[Общая информация]()

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

---

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

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

</syntaxhighlight>

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

[[Файл:Help_18.png|center]]

==Ссылки==
'''Ссылки''' - являются основной структурной единицей оглавления и состоят из:
*''названия главы'' (подраздела) - в квадратных скобках,
*''пути к <code>.md</code> файлу'', соответствующему содержимому раздела (указывается относительно корневой папки проекта со всей документацией) - в круглых скобках.

'''Важно:''' для корректного отображения страницы при создании ссылок в пути к файлу необходимо использовать прямой слэш <code>/</code>. 

==Элементы==

'''Элементы''', которые используются при создании оглавлений:
*Ненумерованные главы,
*Ненумерованный заголовок первого уровня,
*Нумерованный заголовок,
*Глава-черновик,
*Разделитель.

----

===Ненумерованные главы===
В <code>SUMMARY.md</code> таким главам соответствует ссылка без знака <code>-</code> и табуляции.

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

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

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

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

----

===Ненумерованный заголовок первого уровня===
В <code>SUMMARY.md</code> таким заголовкам соответствует текст с одним знаком <code>#</code> в начале.

Заголовки уровня <code>1</code> можно использовать в качестве заголовка для следующих пронумерованных глав. 

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

Заголовок отображается как некликабельный текст. 

Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо.

Заголовки частей должны быть заголовками уровня <code>h1</code> (один <code>#</code>), другие уровни заголовков игнорируются.

----

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

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

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

Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция

----

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

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

'''Главы-черновики''' - это главы без файла и, следовательно, контента. 

Обычно используются разметки структуры документа, когда отсутствует содержание глав. 

Такие главы отображаются как неактивные ссылки в оглавлении. 

Главы-черновики пишутся как обычные главы, но без записи пути к файлу

----

===Разделитель===

'''Разделитель''' - это строка, содержащая три и более тире: <code>---</code>.

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

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

Для удобства разработки документации, формирования понятной файловой структуры и корректного отображения содержимого генерируемой веб-страницы необходимо следовать следующим правилам:
*файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления;
*для каждого раздела создаётся директория; 
*для корневых разделов директории с описанием находятся в корне проекта <code>src</code>;
*если раздел содержит подразделы, создаются поддиректории внутри раздела;
*в директории каждого раздела находятся файл с расширением <code>.md</code>, с документацией соответствующей главы;
*названия всех папок и файлов должны быть без пробелов;
*если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка <code>assets</code>, в которой размещаются файлы изображений;
*изображения именуются как <code>asset_1</code>, <code>asset_2</code>, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся.

Ниже приведён ''пример оглавления'' в <code>SUMMARY.md</code> и соответствующая ему ''файловая структура''.

<syntaxhighlight lang="markdown">
[Общая информация]()

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

---

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

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

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

[[Файл:Help_19.png|center]]

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

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

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

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

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

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