Давайте знакомиться
Каждая разработка, если она хоть немного поэтичней, чем печать «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
предметный указатель
комментарии (50)
быстро вы :)
Покрутите и вот это (freeware version) helpinator может еще какие идеи придут к вам.
Нет визуального редактора, но зато я могу полностью котролировать визуальное представление, список выходных форматов больше. А главное исходник каждой статьи это отдельный текстовый файл, в котором только контент без представления, потому я могу держать проэкт в mercurial или svn репозитарии и видеть изменения обычным diff-ом. Отдельные файлы позволяют работать над документацией совмесно нескольким людям. Для редактрирования RST пользуюсь e-TextEditor или Vim.
Я дописал несколько разширений для форматирования рисунков при конвертировании в html, а также вставку swf, с Help & Manual такое пока невозможно, только планируется интеграция с SandCastle.
Но в любом случае выбор конкертного инструмента зависит от вашей задачи.
Думаю интерактивную справку по продукту в chm или Help2 нужно в Help & Manual или RoboHelp делать, а вот html или pdf, а также документацию по проєкту для разработчиков мне удобне делать на Sphinx.
Их явно не хватает в обзоре.
Однако таки да. Про Вики забыл. Более того, опыт работы с dokuwiki при написании документации тоже сыграл в пользу написания рекламируемой программы.
Вот, что я имею против вики:
а) Самое главное. Я не могу в вики разделять документацию по релизам. Вот сделал я релиз 1.0, и начал работать над 2.0. при этом в 1.0 продолжают вноситься фиксы, что-то правится в доке. А в 2.0 меняется интерфейс и дока меняется сильно. В вики такое разделение делать неудобно. А в случае, если твои текстовые файлы с документацией лежат прямо в svn, все прозрачно и удобно. Я всегда могу сделать чекаут нужной версии документации, хоть первой ветки, хоть второй.
б) Механизма выделения файлов контента из программы вики. Чтобы бэкапиить перекидывать с локально машины на сервер и обратно. Каждый раз приходится упаковывать всю папку с вики.
в) Все-таки в вики мне не хватает свободы писать в HTML. Хочется как-то иногда отформатировать, но натыкаешься на ограничения.
в каком-то это может быть (специально не изучал)
Конечно решаемо все :) Но иногда хочется удобства.
forum.agiledev.ru/index.php?t=msg&th=1168&start=0&
но это уж очень сырой материал.
Из приятностей:
1) наотличненько сочитается с SVN и eclipse, оформление меняется не зависимо от контента (путем хачения скрипта)
2) Удобно включать всякие полезности вида картинок-диаграмок-сырцов (все с версиями!)
3) Снапшоты, версии и бранчи делаются на уровне SVN вместе с сырцами. Хотя такого чтобы на бранч документацию писали отдельную моя седая голова не припомнит ;-)
4) 0-install, перлоскрипт прилетает по «svn get...».
5) типографский вывод для печатной доки.
6) один исходник для разных форматов (ну, партитура для танца с бубном прилагается)
Из неприятностей похода:
1) Нет визуального редактирования (техрайтера мелко колбасило при виде эклипса, с подавляемыми рвотными позывами)
2) Проверка орфографии штатная из эклипса (не удобно, как результат туча очепяток). Почти помог проход ispell.
3) Генеряемое не отличается читабельностью на уровне кода. Периодически бывают косяки вида ускакавших хрен знает куда иллюстрации в DVI, overfull/underfull в пол-страницы, косяки в HTML коде и прочее. Так как доку генеряют за 3 часа до релиза, обычно это довольно стрессовые моменты.
4) Перлоскрипт становится священной коровой, обретает интеллект, характер, астральное тело и начинает требовать жертвоприношений.
С того момента были предприняты попытки писать доки в sharepoint-е (стартует на ура, но получение печатной копии — непреодолимая проблема, снапшот для релиза — делается через API большой геморрой). В итоге чуется вернемся к перлу. Вопрос по сей день открыт.
1. Действительно работа с документацией в SVN была очень сильным мотивом взяться за эту работу.
2. Насчет хаченья скрипта для смены оформления. Тут все культурненько — есть темы. Хачить не надо.
3. Орфография ну да-да. Мы опенофисом просто втупую вычитываем перед релизом. Но подозреваю, что можно копать в сторону ispell и интеграции с текстовым редактором.
4. Я пока не улез особо в дебри. По крайней мере HTML вполне читаем… Кстати, кстати… про TeX я очень даже подумываю :))))
5. Против священной коровы и характера все-таки хочется надеяться что поможет постоянный code-review, и таки проект обвешан модульными тестами.
Вернетесь к перлу :)))) sure.
Но лично мне удобнее html, главное чтобы редактор удобный был, в котором пишу.
Ваша ссылка на asciidoc. Большое за нее спасибо! Если бы я прочитал этот Ваш топик, с большой вероятностью я бы допиливал asciidoc под себя. Он очень близок к тем задачам, что решает мой BullDoc (ну при наличии cgi-шки, которой наверное нет в открытом доступе. Выложили бы — спрос бы был наверное).
Да и просто если бы Вы зашли ко мне на сайт, там навигация и от корня достаточно прозрачная: Software->asciidoc.cgi.
Еще раз спасибо за коментарии.
Этот прект и Ваше его использование крайне близко к тому, для чего писался BullDoc. Однако все же это взгляды под разными углами.
Аскидок больше нацелен на удобную разметку. И ваш скриптик дает возможность предпросмотра страницы без полной сборки всего документа.
На выходе в родном варианте генерится монолитный html файл (если говорить о выводе в html), а это не всегда удобно. Прочие приемы требуют еще и наличия докбучных инструментов.
Мой же проект предполагает выносить парсеры разметки в плагины. И нацелен на сборку статической книжки из многих html файлов. И на сборку CHM. Понятное дело, что и монолитный файл документации для распечатки тоже создается. Т. е. моя программа это не рендерер, а собиратель и построитель навигации, предметного указателя, и пр. Всяких парсеров я прикручу еще. Очень хочется маркдаун прикрутить в первую очередь.
DocBook это стандарт, достаточно зрелый и правильный, вполне подходящий для такого рода документации. И для DocBook есть куча разнообразного софта. Единственный недостаток (IMHO) DocBook — в нём неудобно писать текст — решается использованием для написания текста AsciiDoc. А когда текст уже написан и отконвертирован в DocBook, то корректировать текст по мелочи можно и в самом DocBook, чтобы не морочиться повторной конвертацией из AsciiDoc (особенно если после конвертации в DocBook этот DocBook активно довёрстывался с помощью софта для DocBook).
А возможность получить из AsciiDoc сразу html — это удобно для публикации небольших документов, для предварительного просмотра в процессе подготовки большого документа (чтобы не возиться с DocBook пока документ не будет готов), и для wiki.
Насколько я понимаю, Ваш BullDoc по назначению ближе к DocBook. Возможно, Вам стоит более внимательно поглядеть на DocBook (держа в голове что подсветку синтаксиса можно получить автоматом при конвертации из AsciiDoc в DocBook, и что с DocBook надо поработать через специальный софт, а не ручками с XSLT).
Да я вроде понимаю, что DocBook идеологически правильный стандарт. И долгое время я на него смотрел, но что-то не сложилось у меня с ним.
Может еще сложится :)
Что такое подсветка синтаксиса. Когда Вы пишите программу или просто html файл, удобно, когда текстовый редактор подсвечивает ключевые слова и скобки разным цветом. Также и читать удобнее программу, если она подсвечена. Например вот так:
bulldoc.ru/screenshots/highlight.png
1. Когда встает вопрос в чем писать пользовательскую документацию, один их ответов бывает Word.
2. Если мы пишем документацию для проектов веб-разработки, то там часто используются примеры кода. Особенно если это документация для разработчиков (которые тоже пользователи системы). Код удобно подсвечивать.
3. В Word нет подсветки кода.
А не подскажете где взять такие макросы?
Тем более, автоподстветка изредка ошибается, для фрагментов шанс ошибочного расцвечивания ещё выше.
ну а так вопрос свелся к подсвечивать код или нет. он наверное философский.
А в Вашем случае, Вы можете поставить знак ударения над буквой «ё»?
У латеха язык свой. Его учить надо? Надо. А с полпинка не выучишь. Он на выходе хтмл дает статический? А я хочу именно этого. Он CHM на выходе может? А мне надо. А над ё мне ударение не надо. И формулы я в своей программерской деятельности не набираю, а вот код подсвеченный в документации мне нужен. И его Латехом я наверное тоже не смогу обеспечить, так?
Чтобы посмотреть, что получится я каждый раз компилить должен, так ведь? А это не удобно.
Ну так получается Латех для моей задачи НЕ ГОДИТСЯ. Хотя он и уруливает, и DVI рулез.
Код форматировать LaTex может при помощи пакета Listings. А html из него можно получать при помощи Hevea.
С другой стороны, LaTex, конечно, скорее предназначен для статей и книжек, чем для документации.
Они очень хорошо аргументировали свою позицию и я с ними согласен. LaTEX хорош для создания печатной документации, но сейчас печатают мало зато в онлайне кусок примера посмотреть это часто, а ещё ссылки и много другого.
Потому на входе как раз у них ReSructured Text, а на выходе формат какой задашь тот же LaTEX.
А по сути дела, приятно, что какие-то движения есть, но я как-то на докбук перешел и норм. Поначалу пришлось, конечно, покопаться, зато после созданиях всех нужных шаблонов и батников для автопарсинга стало хорошо. А XML каждый техрайтер из отдела может править в своем любимом редакторе, никого ни к чему не принуждаем. Ведь отличное знание текстового редактора (набор привычных макросов, хоткеев, темплейтов) — это огромный бонус в производительности техписа.
Каринки я обвел рамками через стили, но добрый хабр стили повырезал.
Картинки можно было делать скриншотами, отмасштабированными к 500 пикселам, но хотелось, чтобы текст был виден. Возможно это неудачно. Что-то пробовал так и эдак и не очень получилось видимо.
Суть же постарался изложить :)
Докбук хорош :) но с ним есть определенные неудобства, выше в обсуждении это упоминается. Конечно, как универсальный формат Докбук очень удобен и конкурировать с ним нет смысла.
Однако с точки зрения удобства для себя, я не поленился и написал свой инструмент.
По поводу скринов, просто можно было их обрезать чем-то типа волнистых черт, чтобы буквы не резать посередине, смотрится неопрятно. Обычно во всех продвинутых программах для снятия скриншотов есть такие возможности.
Сайт, кстати, понравился, быстрый и симпатичный :). Одно замечание только, что сразу бросилось в глаза: "«Оформление и настройки". В заголовках по одной кавычке напрягает немного, чувство незавершенности вызывает :). Лучше бы или вообще без кавычек, или с двух сторон.
В общем, удачи! Приятно, что адекватно восприняли мой комментарий, я на самом деле без суровости, а наоборот, с лучами добра :). Сейчас перечитал, подумал, что немного грубовато :). Но тут уж такие дела, вы пиарите свой инструмент, а я свой, докбук :). Чем больше народу с ним будет возиться, тем всем будет проще =).
Про волнистую линию хорошая мысль, спасибо.
"«Оформление и настройки". Эта кавычка, для многих привычный значок, заменяющий стрелочку. Это стрелка назад и название предыдущей главы (в докбуке есть такой элемент, когда вы строите html-книгу). Возможно стоит нарисовать стрелочку картинкой или другим значком.
Мой инструмент, кстати, не полный конкурент докбуку. Они пересекаются, но не совпадают. Вот смотрите, какая идеология у моего BullDoc:
1. Есть исходник документации в некотором формате (это обязательно должен быть текстовый файл). Пока это html, с некоторыми служебными вставками. Но в планах сделать поддержку маркдаун, вики, и приколоться — сделать поддержку docbook (взять парсер вот из этого проекта wiki.php.net/doc/phd)
2. Этот исходник при отображении прогоняется через соответствующий парсер. Пока это только html-примитивный парсер.
3. Из того что получилось делается книжка с оглавлением, меню разделов, стрелками вперед-назад и предметным указателем. Причем понятно, что неудобно после каждой правки собирать весь проект, чтобы посмотреть, что получилось. Для этого есть возможность смотреть это через веб сервер, без полной пересборки. В комментариях есть похожий проект, касающийся именно докбука, — чтобы набирать не в XML, а в чем-то, что легко переносится в докбук, и чтобы смотреть результат онлайн без полной пересбоки.
Поэтому Докбук и BullDoc вполне могут мирно дружить.
например вот этот пример меня совсем не вдохновил:
www.php.net/~helly/php/ext/spl/
>Т. е. по-вашему ваша же тулза больше «вдохновляет» чем doxygen
Ну это уже вопрос философский — его сложно обсуждать в споре. Моя тулза другая. Она отличается от генераторов документации по API на основе кода. С помощью нее можно сделать опрятную книжку и не только про API.
Зато конечно моя тулза не умеет генерить документацию по API, да это и не нужно, т. к. и так есть такие инструменты.
Так, что вдохновляет, да :)