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

Софт для написания документации

Принцип написания документации

  • Все изменения конфигов должны попадать в git
  • Документация серверов должна вестить от корня /
Пример
├── server.ru
│   ├── etc
│   │   ├── cron.d
│   │   │   ├── 0hourly
│   │   │   └── sysstat
│   │   ├── cron.daily
│   │   │   ├── etckeeper
│   │   │   └── logrotate
│   │   ├── cron.hourly
│   │   │   └── 0anacron
│   │   ├── crontab
│   │   ├── fail2ban
│   │   │   ├── filter.d
│   │   │   │   └── apache-badbots.conf
│   │   │   └── jail.conf
│   │   ├── goaccess.conf
│   │   ├── hosts
│   │   ├── nginx
│   │   │   ├── bx
│   │   │   │   ├── conf
│   │   │   │   │   ├── bitrix.conf
│   │   │   │   │   ├── ssl.conf
│   │   │   ├── nginx.conf
│   │   │   └── ssl
│   │   ├── passwd
│   │   ├── php.ini
│   │   ├── rc.local
│   │   ├── sudoers
│   │   ├── sysctl.conf
│   │   ├── vsftpd
  • У каждого сервера в корне репозитория должен быть файл readme.md с документацией по данному серверу

Программное обеспечение

Основной инструмент для создания Markdown файлов, это VSCODE

Visual Studio Code Plugins

  • Auto MarkdownTOC - для генерации содержания
  • Markdown All in One - для подсветки синтаксиса и других полезных сценариев

MkDocs

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

Ссылки

Deploy документации в GitHub

deploy.bat

В данном примере используются два репозитория origin, gh-pages и branch gh-pages для публичного репозитория

cmd set OUTPUTDIR=site set GITHUB_PAGES_REMOTE=gh-pages set GITHUB_PAGES_BRANCH=gh-pages mkdocs gh-deploy -m "Generate MkDocs site" -r %GITHUB_PAGES_REMOTE% -b %GITHUB_PAGES_BRANCH% -d %OUTPUTDIR% --force rd site /S /Q