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

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

Материал из Химсофт Вики
← Предыдущая правка
Sidminik (обсуждение | вклад)
Бюрократы, Администраторы интерфейса, Скрывающие, Администраторы
2629 правок
 
(не показано 17 промежуточных версий этого же участника)
Строка 3: Строка 3:
*распределение <code>.md</code> файлов в файловой структуре согласно иерархии.
*распределение <code>.md</code> файлов в файловой структуре согласно иерархии.


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


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


Файл является неотъемлемой частью документации и должен находиться только в корне проекта.
Файл является неотъемлемой частью документации и должен находиться только в корне проекта.
Строка 15: Строка 15:
Оглавление, описанное в <code>SUMMARY.md</code> состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе.
Оглавление, описанное в <code>SUMMARY.md</code> состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе.


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


Строка 21: Строка 20:
[Общая информация]()
[Общая информация]()


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


## Глава 2
# Глава 2
- [Описание работы и синтаксиса скриптов]()
- [Описание работы и синтаксиса скриптов]()
   - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
   - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
Строка 45: Строка 44:
[[Файл:Help_18.png|center]]
[[Файл:Help_18.png|center]]


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


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


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


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


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


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


===Ненумерованный заголовок первого уровня===
===Ненумерованный заголовок первого уровня===
В SUMMARY.md таким заголовкам соответствует текст с одним знаком # в начале.
В <code>SUMMARY.md</code> таким заголовкам соответствует текст с одним знаком <code>#</code> в начале.
 
Заголовки уровня <code>1</code> можно использовать в качестве заголовка для следующих пронумерованных глав.
 
Это можно использовать для логического разделения различных разделов документа.
 
Заголовок отображается как некликабельный текст.  


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


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


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


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


Главы-черновики - это главы без файла и, следовательно, контента. Обычно используются разметки структуры документа, когда отсутствует содержание глав. Такие главы отображаются как неактивные ссылки в оглавлении. Главы-черновики пишутся как обычные главы, но без записи пути к файлу
В <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> и соответствующая ему ''файловая структура''.
Для каждого раздела создаётся директория; для корневых разделов директории с описанием находятся в корне проекта src
Если раздел содержит подразделы, создаются поддиректории внутри раздела
В директории каждого раздела находятся файл с расширением .md, с документацией соответствующей главы
Названия всех папок и файлов должны быть без пробелов
Если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка assets, в которой размещаются файлы изображений
Изображения именуются как asset_1, asset_2, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся
Ниже приведён пример оглавления в SUMMARY.md и соответствующая ему файловая структура
 
Оглавление в SUMMARY.md:


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


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


## Глава 2
# Глава 2
- [Описание работы и синтаксиса скриптов](Описание_работы_и_синтаксиса_скриптов/Описание_работы_и_синтаксиса_скриптов.md)
- [Описание работы и синтаксиса скриптов](Описание_работы_и_синтаксиса_скриптов/Описание_работы_и_синтаксиса_скриптов.md)
   - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
   - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)

Текущая версия от 07:36, 13 мая 2026

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

  • создание (редактирование) файлов расширения Markdown, каждый из которых является отдельным документом и соответствует определённой главе или подразделу;
  • распределение .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 и соответствующая ему файловая структура. 

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

# Глава 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=2808