Давайте знакомиться
Каждая разработка, если она хоть немного поэтичней, чем печать «hello world», требует документации. И как-то так получалось, что я начинал писать документацию и все время наталкивался на то, что мне это неудобно:
Документация в MS Word (Open Office) не имеет подсветки кода, держит все в одном длинном документе, его не положишь в систему контроля версий для отслеживания изменений. Такой документ невозможно без лишних трудностей сохранить в html-коде, который будет размещён на сайте.
Microsoft HTML Help Compiler позволяет все хранить в тексте, но не имеет подсветки синтаксиса, документ нельзя собрать в связанные html-страницы для выкладывания на сайт без active-x компонента
Формат Docbook тоже близок к желаемому, но XSLT трансформации сложны, подсветка синтаксиса — хоть и решаемая, но проблема.
PHPDocumentator нацелен на написание документации в виде комментариев к коду. Да, он поддерживает подключение нескольких страниц чистой документации к тому, что получилось (кажется это называется там термином тюториал). BullDoc направлен на написание документации в чистом виде — в виде книжки. Опрятной нормальной книжки с главами, разделами, оглавлением и индексом. То, что получается на выходе из PHPDoc это рабочий инструмент, никак не документация для конечного юзера.
В результате появился небольшой скрипт для документации, который был причесан, задокументирован и предложен обществу.
так выглядит документация
Как у любой программы, заточенной под качественное выполнение определенной задачи, у BullDoc есть четкие цели:
- Структуры книги (оглавления) формируется с помощью файла в простом и популярном формате YAML
- Страницы должны храниться в папках в соответствии со структурой книги
- Содержимое страниц представляет собой html текст, который можно открыть прямо в браузере
- Текст страниц может содержать специальные тэги для ссылок на страницы из оглавления
- Текст страниц может содержать специальные тэги для подсветки синтаксиса
- Для вставки картинки достаточно положить ее рядом с файлом текста страницы, а в тексте вставить обычный тэг картинки с атрибутом src='myimage.jpg' или src='myimages/myimage.jpg'
- Системой для страницы формируется меню текущего уровня со ссылками на разделы выше по иерархии. Например для статьи Хобби/на открытом воздухе/рыбалка/блесны, меню будет содержать соседние статьи (крючки, лески, удилища и т.д.), и ссылки на родительские разделы: «на главную», «хобби», «на открытом воздухе» и «рыбалка». Формируются ссылки «вперед» и «назад»
- Должен быть предметный указатель. Ключевые слова назначаются с помощью специального тега, на их основе автоматически формируется страница «Предметный указатель».
Полный список характеристик системы можно посмотреть на сайте программы.
файл оглавления в формате YAML
Как можно использовать BullDoc?
Программа работает в двух качествах — как веб-приложение под управлением веб-сервера Apache, или как консольное приложение из командной строки. В первом случае, вы можете смотреть результаты своей правки не собирая проект в статические файлы, править тексты через веб-интерфейс. А из командной строки вы собираете уже написанную справку в готовый к использованию конечными пользователями вид (статический HTML или CHM).
Многие программисты ведут блоги. В блогах мы пишем много разного — от коротких сообщений, вроде «Как хочется пива» до статей в нескольких частях с прологом и эпилогом. Стараемся поддерживать рубрикацию наших записей с помощью тегов. Блог хорош тем, что туда можно выложить интересную мысль, которая еще не оформилась в виде полноценной статьи. Однако часто хочется объединить несколько постов в один, когда мысль оформится. Страшно подумать, но когда-нибудь из нашего блога могла бы получиться самая настоящая книжка. Возможно в этом вам поможет BullDoc.
правка через веб-интерфейс
Где взять?
www.bulldoc.ru
Задачи, цели и возможности программы
FAQ
Пример шаг-за-шагом
Документация
Скачать
Для разработчиков:
Проект на GoogleCode
Репозиторий SVN
предметный указатель
