Использование 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 на лету.
    Поделиться публикацией
    Похожие публикации
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама
    Комментарии 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 стандартнее ;)

                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.