Github + Markdown = Viewdocs

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

Когда я перерос README на Github, я рассматривал только 2 варианта для документации: Github Pages ^[1] и Read the Docs ^[2]. К сожалению, у меня возникли проблемы с обоими. Главным образом, Read the Docs заставляет меня использовать reStructured Text, а Github Pages подразумевает поддержку отдельной ветки и использование генератора статичных страниц.

На самом деле, я бы хотел иметь нечто похожее на Gist.io ^[3], только для моего репозитория. Не найдя ничего подходящего, я написал это сам.

Я называю это Viewdocs ^[4]. Сервис на лету создает страницы из markdown в папке docs Вашего проекта. Установка не требуется, просто следуйте соглашениям. Возможно для Вас это уже работает, т.к. markdown в папке docs — не такая уж редкость.

Шаблон, используемый по-умолчанию, был позаимствован у Gist.io.

Узнать больше Вы можете на сайте Viewdocs, который работает на базе Viewdocs. Или вот небольшой скринкаст-введение:

Автор: truezemez

Источник ^[5]