Kameraden,
Уже, бывало, поднимался вопрос об инструментах документирования, но сейчас он поднялся и у меня)
Сейчас стоит задача переехать с GitBook на что-то другое. Требования примерно следующие:
1. Возможность self-host на своих мощностях
2. Возможность какими-либо либо плагинами (что-то связанное со swagger) генерить и размещать документацию по REST.
2.1. В документации по REST обязательно будут блоки кода, желательно в них иметь подсветку синтаксиса.
3. Обязательно наличие продвинутой системы контроля версий
4. Максимальная кастомизируемость внешнего вида (чтобы можно было привести в соответствие с корп.стилем)
5. По возможности поддержка легковесных языков разметки (md / rst) as a plus.
6. Возможность подключения статических анализаторов (линтеров). Чтобы часть труда по ревью переложить на железные плечи.
7. Ну и возможность легко и просто прикручивать различные плагины (типа формы обратной связи, "Previous/Next Article" и так далее).
Сейчас смотрю на Github Pages, он, кмк, в той или иной степени отвечает этим требованиям. На нем, насколько я сделал вывод, многие крупные вендоры строят свою доку, типа Яндекс.Облако или Майкрософт.
Но хотелось бы и мнение сообщества выслушать) по правильному ли пути я иду? какие шишки набью? что мне еще посмотреть?