6 августа 2007 в 19:49

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

Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:
  • Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
    • Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
    • Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/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 на лету.
Alex Efros @powerman
карма
303,5
рейтинг 0,0
Systems Architect, Senior Go/Perl Linux Developer
Самое читаемое Управление

Комментарии (22)

  • 0
    Упс, прошу прощения, совсем забыл. Пару дней назад expire-нулся домен asdfgroup.com, в котором находится мой сайт powerman.asdfgroup.com - владелец домена не уследил, и должен сегодня-завтра домен восстановить. Так что пока последние две ссылки в статье не работают, извините.
    • 0
      Домен восстановили, ссылки должны заработать.
  • 0
    Всё здорово, но есть пара вопросов:
    Как создаются ссылки между разными документами?
    Как происходит навигация внутри документа, когда он еще не преобразован в html? Есть ли какие-либо плагины к Vim'у (и к другим текстовым редакторам)?

    А в первом приближении всё это очень сильно напоминает один из многочисленных вики-диалектов, типа Textile.
    • 0
      Если бы еще была интеграция с каким-нибудь редактором, кроме Vim'а (и Emacs'а ;)), я бы, наверное, использовал бы эту штуку для написания постов в блог и для оформления простеньких html-страничек. Чтобы не возиться с html'ем и оформлением напрямую. =)
      • 0
        AsciiDoc не нужна интеграция, он отлично выглядит и пишется/читается даже без подсветки синтаксиса, хоть notepad используйте.
        • 0
          Я не в смысле подсветки синтаксиса. Хочется, чтобы можно было бы сделать так: написал кусок текста в синтаксисе AsciiDoc, нажал кнопочку - получил этот кусок в буфер обмена уже в виде html-фрагмента. А в идеале еще и вторую кнопочку - для предпросмотра в HTML.
          P.S. Я знаю the power of UNIX command line =) Но лениво, ей богу.
          • 0
            Э... дык у нас примерно так всё и работает. Написал часть текста, сохранился, нажал refresh в браузере и посмотрел как написанный текст выглядит в html.
            • 0
              Но тогда её надо крутить либо на локальном веб-сервере, либо лезть за этим в интернет, так?
              • 0
                Да, надо локальный веб-сервер. Наша группа, в основном, занимается веб-разработкой, так что локальный вебсервер у всех настроен в любом случае. :)

                А вообще никто не мешает повесить в .vimrc hook на запись .txt-файлов в указанном каталоге, который рядом с этим .txt файлом будет в один вызов команды asciidoc класть .html-файл, и вторым вызовом какой-нить утилитки копировать его содержимое в буфер обмена (кстати, а зачем это нужно?).
                • 0
                  Ну вот я и говорю, the power of UNIX command line =)
                  Нужно, например, чтобы в блог/ЖЖ/комменты к хабру быстро писать красивый html-код.
          • 0
            А что касается "лениво", то мне гораздо проще один раз написать простейший скрипт для выполнения обработок текста одной кнопкой, чем постоянно набирать документацию в формате а-ля docbook.
            • +1
              Это безусловно.
              Мне, конечно, не надо писать docbook'и, но набор текста в html'е удручает.
              WISIWYG, зачастую, удручает не меньше.
    • +1
      Ссылки создаются так:

      1. К обычным url добавляются скобки а-ля http://ya.ru[] в которых можно написать текст ссылки а-ля http://ya.ru[Яндекс]
      2. Ссылки на "соседние" страницы/файлы этой-же доки с помощью схемы "link" а-ля link:otherpage[] или link:subdir/index.html[Описание фичи subdir]
      3. Картинки вставляются так image::images/icons/home.png[Alt text]
      Навигация до генерации html не происходит никак. Разве что вы пользуетесь достаточно умным текстовым редактором (напр. Vim) и научите его распознавать конструкцию link: для открытия новых файлов. Плагины может и есть, но у меня в них пока потребности не возникало, и я их просто не искал. А вообще это должно очень просто реализовываться, на уровне нескольких строк в .vimrc и без всяких плагинов, я думаю.

      Вики действительно напоминает. Но есть и отличия - более интуитивная и простая разметка чем у всех виденных мной вики-диалектов, и возможность работать напрямую с файлами.
  • 0
    link:otherpage[]

    otherpage - это якорь в тексте?
    В остальном понятно, спасибо!
    • 0
      Нет, якоря (ссылки внутри текущего документа) делаются иначе, а выше ссылка на файл otherpage.txt лежащий в одном каталоге с текущим файлом.
  • 0
    Любопытно, насколько различаются наши с Вами требования к системе документирования.
    • 0
      Я именно поэтому начал именно с требований. :)

      А какие у Вас требования к системе документирования?
  • 0
    кажется, это очень похоже на markdown
    • 0
      Да, такого типа систем некоторое кол-во. Ещё из популярных есть reStructuredText. Как раз эти, и некоторые другие я и сравнивал, когда подбирал для себя систему.

      В частности, markdown "заточен" под html, и позволяет делать штуки типа встраивания html-тегов в исходный .txt-файл. А это автоматически означает смешивание структуры документа и его представления, и невозможность его корректно перегнать в тот же docbook.
  • 0
    Наша команда предпочитает doxygen, у него есть два плюса, по крайней мере для нас - он инлайновый и почти похож на Latex, что сильно упростило его изучение.
  • 0
    javadoc?
  • 0
    DocBook может и стандарт де-факто, только LaTeX стандартнее ;)
  • Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.