[Решено] Автодокументация с применением wiki-разметки (делаю. надо ли продолжать или уже есть?)

Полезные советы и программы от пользователей нашего форума.

Модератор: Модераторы разделов

Ответить
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

[Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

Так господа... просветите меня по следующему вопросу.

Озадачился я тут некоторое время назад вопросами создания автодокументации из исходников.
По крайней мере - извлечения документации из исходников.

В общем пишу автодокументатор. для себя. Вопрос в том что может быть я просто не нашел ничего такого из уже существующего (или плохо искал или не разобрался?).
Ключевая фича мне потребная - использование wiki-разметки, которая потом конвертируется в html.
Программ конвертации wiki2html написанных на C++ я не нашел (только одинокая гуёвая утилита на Java писанная), то, собственно, начал ваять собственное "произведение".

Ниже изложу то, что есть, а вас попрошу ответить на вопрос - есть ли что подобное УЖЕ - может мне стоит пока не поздно переключиться на какой стандартный автодокументатор? времени много разбираться не было... потому получив первые результаты, когда запал несколько поостыл... я все-таки задумался )))))

и так. что есть сейчас.

из исходника типа приведенного ниже :

Код:

class stdInReader : public QThread //::=класс $1= \n $* { Q_OBJECT public: //::==$0== // а эта заметка не будет извлечена потому что начинается не с "::". stdInReader(QObject * parent = 0);//::===$*=== Конструктор int init();//::===$*=== Создает необходимые под-объекты и переводит объект в состояние готовности к выполнению. /*:: \n На выходе $1 отдает: \n 1 if some errors was happened \n 0 of all ok \n -1 if can\`t oopen stdIn \n -2 if can\`t oopen stdOut \n -3 if can\`t oopen stdErr \n */ void run(); //::===$*=== Начинает выполнение потока и работу объета. signals: //::==$0== void received_StdIn(const QByteArray &data); //::===$*=== Приняты данные по стандарному потоку ввода. void fileClosed_StdIn(); //::===$*=== Стандартный поток ввода закрыла передающая сторона. (данных больше не будет) ...

извлекаются нужные нам комментарии с обработкой указаний $0-$9 и $*:

Код:

=класс stdInReader= \n class stdInReader : public QThread ==public:== ===stdInReader(QObject * parent = 0);=== Конструктор ===int init();=== Создает необходимые под-объекты и переводит объект в состояние готовности к выполнению. \n На выходе init(); отдает: \n 1 if some errors was happened \n 0 of all ok \n -1 if can`t oopen stdIn \n -2 if can`t oopen stdOut \n -3 if can`t oopen stdErr \n ===void run();=== Начинает выполнение потока и работу объета. ==signals:== ===void received_StdIn(const QByteArray &data);=== Приняты данные по стандарному потоку ввода. ===void fileClosed_StdIn();=== Стандартный поток ввода закрыла передающая сторона. (данных больше не будет)

Далее полученный текст преобразуется в html аналогично тому как это делается в media-wiki на php)))
(единственное пока отличие - мой конвертор поддерживает "\n").

Кроме описанных выше указаний поддерживаются ссылки [[Имя страницы]], [http://mysite.ru.html имя сайта] и списки
"* элемент списка". Далее планирую ввести автоматическое индексирование разделов, т.е. создание индексного файла "ИмяКатегории" при встрече тега "[[Категория:ИмяКатегории]]"...

Идеи тут следующие: во первых - вики разметка проще и удобнее чем скажем html; можно легко ссылаться на другие страницы, определять разделы, перенаправления; вики-разметка ориентированна на "ручную" верстку.
Полученные wiki-текстовки можно сразу закидывать в online в какой media-wiki. или конвертировать в статический набор html-страничек который поставлять как документацию или вставлять в "систему помощи".

вот значит, господа - прошу совета. надо ли далее развивать эти утилиты или стоит "пока не поздно" воспользоваться стандартным документатором?
Прошу указать мне на какой существующий проект, позволяющий делать аналогичные вещи. Что бы я не занимался фигней)
увы, я не нашел или не разобрался.
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
sciko
Сообщения: 1744
Статус: Ъ-участник
ОС: Debian/Ubuntu/etc

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение sciko »

А зачем нам кусок DidiWiki, когда есть полный проект?

Ещё можно глянуть на предмет Texinfo и DocBook.
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

Texinfo - посмотрел что у него указано в wiki-pedia. имхо, громоздко. Осваивать набор команд долго, и полученный текст не нагляден... комментарий в исходнике все-таки должен быть одновременно ещё и комментарием, а не мозолить глаза программиста "левыми текстовками".
DocBook - аналогично. xml-html - не гут... проще сразу вставлять в текст html-текст, чем осваивать docBook. Но мне html как раз в данном случае и не нравится. потому что проще написать [[страница]] чем <a href="страница.страница">Страница</a>

DidiWiki - ВАУВАУ) очень похоже на то что искал. Если оно позволяет перегонять в консоли текстовки в html страницы - супер.
Ну или по крайней мере найден "донор кода" :rolleyes: сейчас буду смотреть) спс)
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
Аватара пользователя
rm_
Сообщения: 3340
Статус: It's the GNU Age
ОС: Debian
Контактная информация:

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение rm_ »

Программ конвертации wiki2html написанных на C++

Вам шашечки, или ехать?
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

deadhead писал(а):
27.11.2009 17:58
Doxygen

просмотрел по быстрому описания которые доступны по русски...
не вижу как вставить в текст таблицу? (аналог вики-разметки "{| ... ... ... |}") Картинку?
Не вижу как мне вставить в текст ссылку на другую страницу. (wiki-тег "[[страница]]" )
Не вижу как выделить текст жирным? курсивом?
Не вижу как мне сделать распределение по категориям страниц? (wiki-тег "[[Категория:имяКатегории]]") ? скажем я хочу сгруппировать классы по категориям?
использовать для всего этого html-теги? но от этого и хочется как раз уйти...

doxygen не катит(?). убедите меня в обратном если я ошибаюсь..
я хочу получать на выходе удобные для чтения, нормально размеченные описания в стиле таких как в QT-шном Assistant.
С выделением, с переходами на другие статьи (половина которых не является полученными из исходников, или ссылки на функцию или класс - типа "see also:"...), с картинками и таблицами; с минимальным напрягом со стороны программиста который пишет код.
Примеры того что хочу видеть - см 1 или 2 .
Doxygen на такое способен?
я не спорю, доксиген большой и наверное вкусный... но я не вижу вышеописанного. и как минимум wiki-разметка проще, удобнее, чем команды доксигена... текст команд перемешивается с комментарием.. это не есть гут.. имхо...

rm_ писал(а):
27.11.2009 17:57
Программ конвертации wiki2html написанных на C++

Вам шашечки, или ехать?

Мне ехать с шашечками. Даже если шашешки будут маленькие и грязные...

В идеале, я хочу что бы документация создавалась автоматически с минимальными зависимостями от других средств. т.е. у меня проект на C++\QT4 - я хочу что бы он собрался с документацией даже если нет ничего кроме QT4.
Я лучше буду поставлять сорсы автодокументатора в комплекте с программой, чем заставлять пользователя лазить по инету в поисках той системы документации которая у меня используется.

При этом никакого гуя, все из скрипта. На самом деле, я бы может быть и задействовал какой скрипт а-ля wiki2html, если он не требует ничего кроме скажем питона или перла... но он должен быть полностью консольным - что бы использовать его из bash-скрипта. я такого не нашел.... (или не увидел...)
а переписывать для консольного использования куски php-кода из media-wiki - я лучше сам все с нуля напишу. Быстрее будет, и без зависимости от php.
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
Аватара пользователя
rm_
Сообщения: 3340
Статус: It's the GNU Age
ОС: Debian
Контактная информация:

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение rm_ »

Denjs
Вот вполне себе консольное средство для wiki2html, не зависящее ни от чего кроме PHP:
http://code.google.com/p/offlinehtml-plugin/
Пользовался на практике его родительским проектом, работает.
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

2 rm_
о! круто, спасибо. буду смотреть, попробую запользовать.
разметка его местами даже удобнее чем в media-wiki. (таблицы в частности, курсивы, подчеркивания....)


PS: пока не вижу как делать индексные файлы по категориям? т.е. если я категорию вставлю - он создаст страницу-категорию в которой перечислит все страницы в данной категории?.. но это уже можно дописать и самому... ))

а он точно консольный? написано что это плагин для docuwiki.... ладно..поразбираюсь, по впечатлениям доложу)
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

так) всем спасибо)

"offline-doku script from Pavel Shevaev" и в довесок с DocuWiki (сам по себе он не работает) в принципе вполне себе хорошо выполняет роль конвертора txt в вики-разметке в html - страницы.

Лишние полтора метра к дистрибутиву и зависимость от php является в принципе достаточно терпимой платой, даже при том, что в скрипте нет функциональности создания "индексной страницы". С индексной страницей уж как-нибудь разберусь. В крайнем случае, возложу эту обязанность на "документо-извлекатель".

Т.е. сейчас схему получения документации планирую перестроть на следующий лад:
этап 1) wiki-размеченные страницы извлекаются из исходного кода (с помощью моей утилиты), и одновременно составляется индексная страница ( в той-же wiki-разметке например) и/или структура каталогов документации. Полагаю надо будет вводить какой доп тег для моего извлекателя, но это мелочи.
этап 2) с помощью "offline-doku script from Pavel Shevaev" (на php) все дело конвертируется в html.

Всем спасибо ))
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
trdm
Сообщения: 266
ОС: Window XP
Контактная информация:

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение trdm »

Denjs писал(а):
27.11.2009 18:17
doxygen не катит(?). убедите меня в обратном если я ошибаюсь..

Катит. Нормально глотае html-теги.
"убедите меня в обратном если я ошибаюсь..">>Читайте документацию.
Только что скормил ему в *.h - такую мульгу и перегенерил *.html

Код: Выделить всё

/**
    \page uoReportPrint "Технология печати."
    <pre>
    Че надо для печати?
    - нужны параметры страницы (от принтера):
        - размер страницы
        - размер области печати.
    - нужны параметры страницы (от пользователя):
        - Поля: справа/слева/снизу/сверху
        - Колонтитулы: сверху/снизу
    </pre>
    <table>
        <tr>
            <td>Заголовок1</td>
            <td>Заголовок2</td>
        </tr>
        <tr>
            <td>Строка 1</td>
            <td>Строка 1</td>
        </tr>
    </table>
*/


http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
Вот список всех команд, HTML, которые могут быть использованы внутри документации.
qt1L, 2C и прочие "аналоги" 1С.
Смертельная доза aлкoгoля 8 гр. на 1 кг вeсa тела: 80 кг * 8 = 640 гр.
Хотите знать больше?
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

2trdm не спору ради но ради истины.

Прочитайте фразу сразу перед
"убедите меня в обратном если я ошибаюсь.."
использовать для всего этого html-теги? но от этого и хочется как раз уйти...


использовать wiki-форматирование не в пример приятнее b проще чем верстать в html.

во первых:
вместо взгромождения

Код: Выделить всё

    <table>
        <tr>
            <td>Заголовок1</td>
            <td>Заголовок2</td>
        </tr>
        <tr>
            <td>Строка 1</td>
            <td>Строка 1</td>
        </tr>
    </table>

гораздо нагляднее использовать

Код: Выделить всё

^ Заголовок1    ^ Заголовок2    ^
|Строка 1        | Строка 1        |

Согласитесь - есть разница.

Ко кроме форматирования текста, мне нужны структуро-образующие указания. Причем в виде множественной категоризации, как это сделано в media-wiki (см Wikipedia ;) ).
Во вторых:
Как заставить доксиген строить произвольную структуру категорий ? как заставить доксиген включать одну страницу документации в несколько категорий? т.е. мне нужен эффект аналогично тому, что получается поле указания в какой-либо статье в media-wiki такого указания:

Код: Выделить всё

[[Категория:КлассыПечати]] [[Категория:ИндексныйСписокКлассов]] [[Категория:ДочерниеКлассыTPrintPage]]

т.е. что бы эта страница появлялась одновременно в 3-х категориях?

В третьих:
как его заставить генерировать несколько файлов документации из одного физического?

doxygen не катит. увы. не в моем случае.
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
trdm
Сообщения: 266
ОС: Window XP
Контактная информация:

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение trdm »

Denjs писал(а):
30.11.2009 21:15
doxygen не катит. увы. не в моем случае.
ага, я приблизительно так и предполагал...
пс. мне с html проще - меньше мороки. пишешь как должно быть и не клашцаешь себе мозг лишним софтом...
в любом случае из src нормальной документации не сделаешь, прийдется писать подробно и с картинками в нормальных форматах...
qt1L, 2C и прочие "аналоги" 1С.
Смертельная доза aлкoгoля 8 гр. на 1 кг вeсa тела: 80 кг * 8 = 640 гр.
Хотите знать больше?
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

Вот как раз я и собираюсь сделать механизм/систему который позволяет делать из исходников (или внедрять в исходники) нормальную документацию. Причем такую что бы программисту создавать такую документацию было так-же не в напряг как и писать простые текстовые комментарии.

При этом автоматически "смешивать" её с "нормальной" документацией, в сторонних файлах, так что бы на выходе все было единым целым.
Таким, что можно отдавать пользователю. С картинками (см тег [[media:picture.jpg]] ) с кроcc-ссылками ( [[имяСтатьи]] ), с множественной категоризацией и т.д.
Более того - которой будет все равно - быть выложенной в wiki или перегенерированной в html.

"Лишний" софт полюбому - у вас это сторонний doxygen, у меня это заточенный под мои нужды комплект (src2adocs.bin + DocuWiki + некоторые .sh-скрипты) - не вижу большой разницы. только что у меня подсистема сборки документации входит в комплект исходников. ну в общем - дело вкуса.
и время покажет)
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
Аватара пользователя
Denjs
Сообщения: 1685
ОС: SuSe 10.2

Re: [Решено] Автодокументация с применением wiki-разметки

Сообщение Denjs »

К слову:
про разные там вики движки. нарыл клевую ссылку. коаздо клевее чем в википедии

http://c2.com/cgi/wiki?WikiEngines

там в частности 5 движков на C писанных, 4 на C++ , есть на C# писанное, и даже на bash))
в общем конкретно зачетное ссылко.))))

ЗЫ: а у didiwiki на проверку оказался весьма бедный язык форматирования... (
QDroid - Среда исполнения и фреймворк для QtScript.
OTPD - Открытые драйвера промышленных принтеров чеков и этикеток (кроссплатформенная подсистема печати).
Спасибо сказали:
Ответить