Перейти к содержанию

Формирование и актуализация 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)

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

Ссылки

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

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

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

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

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

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

В 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)

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

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

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

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

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

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

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

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

Источник — https://wiki.chemsoft.ru/index.php?title=Формирование_и_актуализация_Markdown-исходников_документации&oldid=2801