Шаблон документации для репозитория

• gerzhan.github.io/gerzhan-tpl-docs-repo
• github.com/gerzhan/gerzhan-tpl-docs-repo

Цель

Унификация описания содержания репозитория

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

00 - About
01 - Roadmap
02 - Development
01 - Process
02 - Getting started
03 - Frameworks & tools
04 - Conventions
05 - Technical documentation
03 - Work in progress
04 - Release notes
05 - Maintenance & Support
01 - Infrastructure
02 - Deploy guide
03 - Technical support
04 - Accounts
05 - Who's who
06 - User documentation

Инструкция

Копирование шаблона

• скопируйте архив из удаленного репозитория и распакуйте zip-архив локально в своем репозитории

# копирование текущей версии шаблона документации для репозитория(проекта)
$curl -LS https://github.com/gerzhan/gerzhan-tpl-docs-repo/archive/refs/heads/main.zip -o docs-tpl.zip
# распаковка только директории с документацией в корне собственного репозитория
$unzip ./docs-tpl.zip 'gerzhan-tpl-docs-repo-main/docs/*' -d './docs'
$mv ./docs/gerzhan-tpl-docs-repo-main/docs/* ./docs/
$rm ./docs/gerzhan-tpl-docs-repo-main/docs/
# удалить архив
$rm docs-tpl.zip

Первичная настройка шаблона

• замените/удалите файл docs/README.md
• замените/удалите в docs/index.html блок Yandex.Metrika counter
• измените описание документации в конфигурации для docsify(window.$docsify) в файле docs/index.html
• установите docsify на локальной машине глобавльно или добавьте в корневой package.json

# установить глобально
$npm i docsify-cli -g
# установить локально
$npm i -D docsify-cli

• добавить в package.json команду запуска сервера отображения документации (при необходимости изменить порт 4233 на другой доступный)

"script": {
+ "docs": "docsify serve ./docs -p 4233",

Локальный запуск разработки документации

• запустить локальный сервер для формирования и просмотра документации

$npx run docs

Примечание

Вы можете изменить имя директории с docs на любое другое имя (_docs, 'repodocs' и т.п.). Использование имени docs позволят настроить GitHub Pages для этой директории.

Первоисточники

• Defining an efficient documentation structure