Как стать автором
Поиск
Написать публикацию
Обновить

Использование asciidoc для документирования проекта

Время на прочтение3 мин
Количество просмотров31K
Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:
  • Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
    • Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
    • Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
    • С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
  • Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
  • Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
  • Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).


В результате, изучив существующие решения, я оставился на системе AsciiDoc. Это утилита, которая конвертирует обычные текстовые файлы (использующие очень простую и интуитивную разметку) практически во что угодно (html, docbook, man, etc.). Причины выбора AsciiDoc следующие:
  1. Очень простой и интуитивный язык разметки. Фактически, глядя на текстовый файл с разметкой AsciiDoc, даже не сразу догадаешься, что это не просто обычный текстовый файл, а «файл с разметкой» — он похож на обычный, аккуратно структурированный текстовый файл. По сути, я до обнаружения AsciiDoc много лет писал обычные текстовые файлы примерно в том же стиле, без всякой мысли их позже конвертировать в другие форматы! Отсутствие явной «разметки» очень облегчает чтение и редактирование текста в обычном текстовом редакторе.
  2. Вообще-то «правильный» формат для технической документации — это DocBook. Но писать в этом формате документацию, что ручками, что с помощью специальных утилит… бррр! А AsciiDoc умеет конвертировать в том числе и в формат DocBook. Таким образом, есть возможность написать основную часть документации в простом и удобном текстовом формате AsciiDoc, а уже потом отконвертировать в DocBook и «причесать», используя специфичные фичи DocBook, которых нет в AsciiDoc — это должно в разы ускорить и упростить написание документации, даже если её нужно сдавать в формате DocBook.
  3. AsciiDoc умеет сам конвертировать помимо docbook в man и html форматы, а если нужно будет что-то другое, то в любой другой формат можно сконвертировать из docbook.
  4. Внешний вид генерируемых html настраивается через css (впрочем, меня пока вполне устраивают и дефалтовые настройки).
  5. AsciiDoc достаточно маленькая, шустрая, и при этом неимоверно расширяемая утилита (впрочем, потребности её расширять у меня пока не возникло).

Далее, мной была быстренько наваяна CGIшка, которая при вызове находила внутри проекта .txt-файл с документацией, соответствующий запрошенной url, конвертировала его с помощью asciidoc в html (с кешированием html-страниц пока не изменится исходный .txt-файл) и возвращала полученный html.

В результате, сейчас система работает следующим образом:
  1. пишутся обычные .txt-файлы в каталоге с документацией, локально, в любимом текстовом редакторе
  2. между разработчиками шарятся эти файлы так же, как и исходный код проекта (патчи или svn)
  3. сразу после редактирования текстового файла можно зайти на соответствующую ему url, и увидеть его в html-формате (html будет перегенерирован на лету и закеширован до следующего изменения .txt)
  4. мы пока этого не делали, но по сути формат asciidoc не принципиально отличается от разметки используемой в вики, так что предоставить возможность редактирования документации через веб а-ля вики проблемы составить не должно

Ссылки:
  • На сайте AsciiDoc можно найти полное описание его возможностей, плюс посмотреть исходники страниц самого сайта в .txt-формате (да, сайт AsciiDoc написан на asciidoc :)).
  • Я составил cheat sheet. Табличка очень актуальная, т.к. возможностей у AsciiDoc дикое кол-во, а реально хватает очень небольшого кол-ва, и хочется этот краткий список иметь под рукой.
  • Описание установки и настройки asciidoc, подсветки синтаксиса для Vim, и моей CGIшки для генерирования html на лету.
Теги:
Хабы:
Всего голосов 29: ↑27 и ↓2+25
Комментарии22

Публикации

Ближайшие события