В мае появилась задача подумать над хранением документации. Где мы только не пытались хранить документацию: и в Dropbox, и в Google Docs. Последнее, где мы остановились, это - Confluence. Совершенно наркоманская система редактирования, потребовалось ставить отдельный плагин, чтобы можно было редактировать чистый HTML. Главная проблема всех этих подходов - рассинхронизация. Документация не соответсвует коду. На втором месте - невозможность автоматической генерации документации в процессе сборки проекта. От системы документации не требуется многого: вставка изображений и кросс-ссылки - более чем достаточно.
Все серьезные проекты хранят документацию в коде. Концепция портабельного билда: клонировав репозиторий, пользователь должен получить абсолютно всё, что нужно для сборки проекта, и, желательно, в текстовом формате, чтобы не пришлось ставить никакого дополнительного софта для редактирования.
Mercurial + Markdown
Хотя README встречались и раньше, а wiki хранилась в репозитории еще на Google Code, но именно с приходом GitHub README.md стало обязательным требованием. Краткое описание проекта, в wiki-стайл разметке markdown. После знакомства с возможностями этой системы на github.io любые сомнения в возможностях разметки пропадают. Приятным бонусом является плагин для IntelliJ IDEA.Очень хотелось получить это на локальном репозитории. Поиск вывел на относительно молодой проект (не первый раз ищу) hgext.markdown от Chris Eldredge. Плагин для mercurial, покрывающий требования к встроенной системе документации на 100%. Когда я его поставил, выснилось, что разметка применяется только к readme, плагин не умеет работать с кодировками (пришлось вспомнить эпичнейший доклад про кодировки), с картинками (необходимое требование), ну и несколько проблем шаблонами вообще и с разметкой в частности.
Pull request or GTFO
В общем все это я пофиксил и заслал Крису толстенный пуллреквест, пару дней назад он принял его. Линуксоиды могут спокойно качать плагин, виндузятники в пролёте, поскольку требуется библиотека а у mercurial встроенный python, и как подсунуть одно в другое, еще не разбирался. Как выкурю - зашлю еще один пуллреквест с инструкцией.Пока ждал - пошел на IRC канал, чтобы найти кого-нибудь с правами на запись в wiki-страницу со списокм плагинов. Оказалось, что особых прав не нужно и достаточно зарегистрироваться (порадовала каптча, которая требует ответить на вопрос про команды mercurial). Вооружившись руководством, создал по фэн-шую страничку плагина.
Темы для mercurial
В процессе ковыряния плагина набрел на встроенную систему шаблонов и тем для hgweb. Внутри крайне разухабистый движок, с доступом ко внутреннему API, позволяющий изобразить решительно всё. Заскриншотил каждую тему и добавил на страницу со списком, чтобы было понятно как каждая выглядит. Кстати, сам mercurial размазан по файловой системе: бинарники лежат в /usr/share/mercurial/templates, а основной код в /usr/lib/python2.7/dist-packages/mercurial. |
| Пять стандартных тем и Markdown, идущий в комплекте с плагином |
