Улучшение документации

[dragomano]

Предлагаю улучшить документацию, перенеся её из Wiki на один из специализированных движков: Material for MkDocs, Starlight, Rspress, VitePress

Плюсы:

• Та же возня с Markdown
• Разделение на разделы вместо одной большой страницы
• Более удобный поиск
• Переключение тем
• Переключение локализаций
• Переключение версий
• Возможность публикации на Github Pages с привязкой к своему домену/поддомену
• Возможность скачивания и локального запуска

Минусы:

• Некоторые вещи (типа блоков warning/info/note) придется переделывать под конкретный движок
• Настройка конкретного движка (могу поделиться примерными конфигами для Starlight/Rspress)
• Нюансы создания версий/веток

Примеры:

Starlight:

Rspress:

Размещение:

Где всё это придется хранить - либо в этом же репозитории, в директории docs (как пример), либо в отдельном репозитории, специально для документации. Настраиваем конфиг для публикации через Github Actions и всё.

[OSPanel]

Предложение хорошее — с документацией действительно давно пора навести порядок. Но сейчас не хочется делать это именно в предложенном формате по двум причинам:

1. Подход к документации
   Мы считаем, что пользователю неудобно постоянно обращаться к онлайн‑документации. Справка должна быть доступна сразу в программе, «здесь и сейчас», прямо в том разделе, где находится пользователь. Как вы уже заметили, мы постепенно переносим документацию в интерфейс (пока что во временный оконный win-интерфейс).

2. Разработка веб‑панели управления (управление через браузер)
   Во‑первых, скоро появится полноценный GUI для большинства задач, и значительная часть текущей документации просто перестанет быть актуальной: пользователю не придётся вручную редактировать конфигурационные файлы домена и т.п.

   Во‑вторых, мы планируем полностью перенести документацию в офлайн — прямо внутрь панели управления. В будущем вся справка будет находиться в этой панели, поэтому отдельная документация в интернете, скорее всего, не понадобится.

Пример реальной страницы из будущей панели — ниже:

[dragomano]

А поиск по доке внутри панели? И как потом делать ссылки на нужные разделы, чтобы делиться с другими?

[OSPanel]

Если поиск будет нужен, то мы его сделаем. По поводу ссылок - веб-панель это обычный локальный сайт, т.е. на документацию можно будет давать ссылку, просто она будет вести не на раздел в Wiki, а на раздел в панели управления: https://ospanel/xxx.

В любом случае будем смотреть и думать как и что, возможно останется и обычная Wiki. Пока мы решили отложить все дела с документацией до выхода веб-панели.