Для ПО с открытым исходным кодом очень большое значение имеет документация. На своем опыте я убедился, что написание хорошей документации зачастую даже важнее написания тестов.
Когда я перерос README на Github, я рассматривал только 2 варианта для документации: Github Pages и Read the Docs. К сожалению, у меня возникли проблемы с обоими. Главным образом, Read the Docs заставляет меня использовать reStructured Text, а Github Pages подразумевает поддержку отдельной ветки и использование генератора статичных страниц.
На самом деле, я бы хотел иметь нечто похожее на Gist.io, только для моего репозитория. Не найдя ничего подходящего, я написал это сам.
Я называю это Viewdocs. Сервис на лету создает страницы из markdown в папке docs Вашего проекта. Установка не требуется, просто следуйте соглашениям. Возможно для Вас это уже работает, т.к. markdown в папке docs — не такая уж редкость.
Шаблон, используемый по-умолчанию, был позаимствован у Gist.io.
Узнать больше Вы можете на сайте Viewdocs, который работает на базе Viewdocs. Или вот небольшой скринкаст-введение:
Автор: truezemez
