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

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

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

  • Все изменения конфигов должны попадать в 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

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

Плагины

awesome-pages

Плагин MkDocs, упрощает настройку заголовков страниц и их порядка Awesome-pages позволяет настраивать отображение навигации без необходимости настраивать полную структуру меню в вашем mkdocs.yml Все это делается с помощью небольшого файла конфигурации, который находится непосредственно в соответствующем каталоге вашей документации. Очень удобно!

Этот плагин работает без nav или pages файле mkdocs.yml. Поддерживается и nav, но вы можете не получить ожидаемых результатов, особенно если ваша структура навигации не соответствует структуре файла.

Установка:

pip install mkdocs-awesome-pages-plugin

Добавте это в mkdocs.yml

plugins:
    - search
    - awesome-pages

Использование:

Просто создаем файл .pages в директории где хотим использовать плагин и пишем в него параметры

collapse_single_pages: true # Не будет показываться название директории, в место него будет показан заголовок первого `md` файла в каталоге
collapse: true              # Запрещает/разрешает сворачивание раздела
hide: true                  # Скрывает директорию

Ссылки

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