Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:
- Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
- Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
- Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
- С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
- Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
- Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
- Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).
В результате, изучив существующие решения, я оставился на системе
AsciiDoc. Это утилита, которая конвертирует обычные текстовые файлы (использующие очень простую и интуитивную разметку) практически во что угодно (html, docbook, man, etc.). Причины выбора AsciiDoc следующие:
- Очень простой и интуитивный язык разметки. Фактически, глядя на текстовый файл с разметкой AsciiDoc, даже не сразу догадаешься, что это не просто обычный текстовый файл, а «файл с разметкой» — он похож на обычный, аккуратно структурированный текстовый файл. По сути, я до обнаружения AsciiDoc много лет писал обычные текстовые файлы примерно в том же стиле, без всякой мысли их позже конвертировать в другие форматы! Отсутствие явной «разметки» очень облегчает чтение и редактирование текста в обычном текстовом редакторе.
- Вообще-то «правильный» формат для технической документации — это DocBook. Но писать в этом формате документацию, что ручками, что с помощью специальных утилит… бррр! А AsciiDoc умеет конвертировать в том числе и в формат DocBook. Таким образом, есть возможность написать основную часть документации в простом и удобном текстовом формате AsciiDoc, а уже потом отконвертировать в DocBook и «причесать», используя специфичные фичи DocBook, которых нет в AsciiDoc — это должно в разы ускорить и упростить написание документации, даже если её нужно сдавать в формате DocBook.
- AsciiDoc умеет сам конвертировать помимо docbook в man и html форматы, а если нужно будет что-то другое, то в любой другой формат можно сконвертировать из docbook.
- Внешний вид генерируемых html настраивается через css (впрочем, меня пока вполне устраивают и дефалтовые настройки).
- AsciiDoc достаточно маленькая, шустрая, и при этом неимоверно расширяемая утилита (впрочем, потребности её расширять у меня пока не возникло).
Далее, мной была быстренько наваяна CGIшка, которая при вызове находила внутри проекта .txt-файл с документацией, соответствующий запрошенной url, конвертировала его с помощью asciidoc в html (с кешированием html-страниц пока не изменится исходный .txt-файл) и возвращала полученный html.
В результате, сейчас система работает следующим образом:
- пишутся обычные .txt-файлы в каталоге с документацией, локально, в любимом текстовом редакторе
- между разработчиками шарятся эти файлы так же, как и исходный код проекта (патчи или svn)
- сразу после редактирования текстового файла можно зайти на соответствующую ему url, и увидеть его в html-формате (html будет перегенерирован на лету и закеширован до следующего изменения .txt)
- мы пока этого не делали, но по сути формат asciidoc не принципиально отличается от разметки используемой в вики, так что предоставить возможность редактирования документации через веб а-ля вики проблемы составить не должно
Ссылки:
- На сайте AsciiDoc можно найти полное описание его возможностей, плюс посмотреть исходники страниц самого сайта в .txt-формате (да, сайт AsciiDoc написан на asciidoc :)).
- Я составил cheat sheet. Табличка очень актуальная, т.к. возможностей у AsciiDoc дикое кол-во, а реально хватает очень небольшого кол-ва, и хочется этот краткий список иметь под рукой.
- Описание установки и настройки asciidoc, подсветки синтаксиса для Vim, и моей CGIшки для генерирования html на лету.
комментарии (22)
Как создаются ссылки между разными документами?
Как происходит навигация внутри документа, когда он еще не преобразован в html? Есть ли какие-либо плагины к Vim'у (и к другим текстовым редакторам)?
А в первом приближении всё это очень сильно напоминает один из многочисленных вики-диалектов, типа Textile.
P.S. Я знаю the power of UNIX command line =) Но лениво, ей богу.
А вообще никто не мешает повесить в .vimrc hook на запись .txt-файлов в указанном каталоге, который рядом с этим .txt файлом будет в один вызов команды asciidoc класть .html-файл, и вторым вызовом какой-нить утилитки копировать его содержимое в буфер обмена (кстати, а зачем это нужно?).
Нужно, например, чтобы в блог/ЖЖ/комменты к хабру быстро писать красивый html-код.
Мне, конечно, не надо писать docbook'и, но набор текста в html'е удручает.
WISIWYG, зачастую, удручает не меньше.
- К обычным url добавляются скобки а-ля http://ya.ru[] в которых можно написать текст ссылки а-ля http://ya.ru[Яндекс]
- Ссылки на "соседние" страницы/файлы этой-же доки с помощью схемы "link" а-ля link:otherpage[] или link:subdir/index.html[Описание фичи subdir]
- Картинки вставляются так image::images/icons/home.png[Alt text]
Навигация до генерации html не происходит никак. Разве что вы пользуетесь достаточно умным текстовым редактором (напр. Vim) и научите его распознавать конструкцию link: для открытия новых файлов. Плагины может и есть, но у меня в них пока потребности не возникало, и я их просто не искал. А вообще это должно очень просто реализовываться, на уровне нескольких строк в .vimrc и без всяких плагинов, я думаю.Вики действительно напоминает. Но есть и отличия - более интуитивная и простая разметка чем у всех виденных мной вики-диалектов, и возможность работать напрямую с файлами.
otherpage - это якорь в тексте?
В остальном понятно, спасибо!
А какие у Вас требования к системе документирования?
В частности, markdown "заточен" под html, и позволяет делать штуки типа встраивания html-тегов в исходный .txt-файл. А это автоматически означает смешивание структуры документа и его представления, и невозможность его корректно перегнать в тот же docbook.