Pull to refresh

BullDoc — система разработки документации

Self Promo

Давайте знакомиться


Каждая разработка, если она хоть немного поэтичней, чем печать «hello world», требует документации. И как-то так получалось, что я начинал писать документацию и все время наталкивался на то, что мне это неудобно:


Документация в MS Word (Open Office) не имеет подсветки кода, держит все в одном длинном документе, его не положишь в систему контроля версий для отслеживания изменений. Такой документ невозможно без лишних трудностей сохранить в html-коде, который будет размещён на сайте.


Microsoft HTML Help Compiler позволяет все хранить в тексте, но не имеет подсветки синтаксиса, документ нельзя собрать в связанные html-страницы для выкладывания на сайт без active-x компонента

Формат Docbook тоже близок к желаемому, но XSLT трансформации сложны, подсветка синтаксиса — хоть и решаемая, но проблема.

PHPDocumentator нацелен на написание документации в виде комментариев к коду. Да, он поддерживает подключение нескольких страниц чистой документации к тому, что получилось (кажется это называется там термином тюториал). BullDoc направлен на написание документации в чистом виде — в виде книжки. Опрятной нормальной книжки с главами, разделами, оглавлением и индексом. То, что получается на выходе из PHPDoc это рабочий инструмент, никак не документация для конечного юзера.

В результате появился небольшой скрипт для документации, который был причесан, задокументирован и предложен обществу.


так выглядит документация



Как у любой программы, заточенной под качественное выполнение определенной задачи, у BullDoc есть четкие цели:


  1. Структуры книги (оглавления) формируется с помощью файла в простом и популярном формате YAML
  2. Страницы должны храниться в папках в соответствии со структурой книги
  3. Содержимое страниц представляет собой html текст, который можно открыть прямо в браузере
  4. Текст страниц может содержать специальные тэги для ссылок на страницы из оглавления
  5. Текст страниц может содержать специальные тэги для подсветки синтаксиса
  6. Для вставки картинки достаточно положить ее рядом с файлом текста страницы, а в тексте вставить обычный тэг картинки с атрибутом src='myimage.jpg' или src='myimages/myimage.jpg'
  7. Системой для страницы формируется меню текущего уровня со ссылками на разделы выше по иерархии. Например для статьи Хобби/на открытом воздухе/рыбалка/блесны, меню будет содержать соседние статьи (крючки, лески, удилища и т.д.), и ссылки на родительские разделы: «на главную», «хобби», «на открытом воздухе» и «рыбалка». Формируются ссылки «вперед» и «назад»
  8. Должен быть предметный указатель. Ключевые слова назначаются с помощью специального тега, на их основе автоматически формируется страница «Предметный указатель».


Полный список характеристик системы можно посмотреть на сайте программы.

файл оглавления в формате YAML



Как можно использовать BullDoc?



Программа работает в двух качествах — как веб-приложение под управлением веб-сервера Apache, или как консольное приложение из командной строки. В первом случае, вы можете смотреть результаты своей правки не собирая проект в статические файлы, править тексты через веб-интерфейс. А из командной строки вы собираете уже написанную справку в готовый к использованию конечными пользователями вид (статический HTML или CHM).

Многие программисты ведут блоги. В блогах мы пишем много разного — от коротких сообщений, вроде «Как хочется пива» до статей в нескольких частях с прологом и эпилогом. Стараемся поддерживать рубрикацию наших записей с помощью тегов. Блог хорош тем, что туда можно выложить интересную мысль, которая еще не оформилась в виде полноценной статьи. Однако часто хочется объединить несколько постов в один, когда мысль оформится. Страшно подумать, но когда-нибудь из нашего блога могла бы получиться самая настоящая книжка. Возможно в этом вам поможет BullDoc.


правка через веб-интерфейс



Где взять?


www.bulldoc.ru
Задачи, цели и возможности программы
FAQ
Пример шаг-за-шагом
Документация
Скачать

Для разработчиков:
Проект на GoogleCode
Репозиторий SVN

предметный указатель


Tags: разработкадокументация
Hubs: Self Promo
Total votes 41: ↑35 and ↓6 +29
Comments 50
Comments Comments 50

Popular right now