Человеческий способ генерации справки в Qt

или можно как-то сконвертировать справку из .html в .qhp, а там уже конвертировать дальше для всяких qt Assistant?

Doxygen умеет генерировать qhp. Иных методов сходу не нашёл

doxygen умеет например.

не имел пока опыта работы с Doxygen. Ничего, освою. Спасибо за наводку Вам и XMs.

В моей справке нужно руками ещё много понаписывать. Главную страницу, продумать иерархию справки(части, разделы и так далее). Doxygen умеет такое?

Умеет. Правда там не очень удобный язык разметки для написания документации помимо документации к api (так сиё туло задумывалось изначально).

Но, де-факто это промышленный стандарт для документирования крестового кода, лучше найти всё равно сложно.

Посмотри сорцы Qt они как раз доксигеном и документированны (были по крайней мере когда я туда последний раз лазал).

понял, спасибо. А есть ли инструменты для написания доков не к API?

Это сложный филосовский вопрос...

Смотря чего делаешь. Например можно вести conluence или ещё какую нибудь wiki.

Если ты хочешь доку на уровне несложного встроенного user manual'a то доксигена тебе за глаза, просто заведи отдельные файлы в которых будешь такую доку описывать. Но если ты делаешь не api, то доксиген не лучший вариант.

Да и масштабируется сиё не очень. Ибо кого то кроме разработчика сложно посадить за написание такой документации. А если ещё нужна и локализация, то придётся скорее всего что-то велосипедить.

• qdoc в оригинале генерирует промежуточную XML-разметку из комментариев в cpp-файлах (некоторые такие файлы ЕМНИП имеют расширение *.qdoc вместо *.cpp, чтобы понятнее было). В исходниках Qt и QtCreator можно найти много примеров. Суровый мануал: qt.apidoc.info/5.1.1/qdoc/qdoc-guide-conf.html
• doxygen тоже может в qdoc (qch), точнее в промежуточное XML-описание. Только в какой-то из старых версий был баг, где сгенерированный XML-файл был некорректным из-за одного тега, позднее баг в doxygen исправили.
• Готовая документация для STL, CMake, Ogre и других библиотек: wiki.qt.io/Qt_Creator_Documentation_Gallery
• Для написания доков к не-API я очень рекомендую Github + файлы Markdown, сам в конечном счёте к такому пришёл.

а как можно организовать локализацию справки через doxygen? а каким можно другими средствами?

Итак, в дополнение к тому, что я узнал здесь про doxygen и много других средств.

Почитал я про doxygen и понял, что по идее сделать справку в нём на нескольких языках, то есть локализовать справку, это просто ад будет какой-то.

Нельзя ли как-нибудь это исправить? Нет похожего средства, как в QT : в tr() всё завернул, потом перевёл спокойно, скомпилил, и вуаля, готова локализация.

Что можете посоветовать?

http://www.di-mare.com/adolfo/p/DoxEsEn.htm — вот здесь, кмк, неплохой пример

мда, извращение то ещё.

Попробуй найти похожий os проект с документацией как у тебя и погляди как они решали эту проблему. Скажу точно, что QtHelp не очень распостранённая штука, хотя и заманчиво использовать сиё api для Qt программ.

Тут просто дело юзекейсов - api редко кто документирует более чем на одном языке, хотя, на форуме http://crossplatform.ru одно время група энтузиастов занималась локализацией справки по Qt, возможно имеет способ посмотреть, как они решали эту задачу.

А вот локализация user manual'a как то должна решаться, скорее всего, нужно думать в сторону чего то типа DocBook что бы текст отдельно, оформление отдельно.

Ещё, возможно стоит посмотреть как работают эти ребяты. Ибо у них есть и дока и локализация и выгрузка в QtHelp.

И да, если не сложно, отпишись о результатах своих изысканий и выборе инструмента по итогам, вдруг пригодиться когда-нибудь, кому-нибудь.

кстати, способ, который подсказал XMs с использованием Doxygen для локализации, довольно интересен. Но всё равно что-то не то.

Спасибо за наводки. О результатах отпишусь позже.

Ещё, возможно стоит посмотреть как работают эти ребяты. Ибо у них есть и дока и локализация и выгрузка в QtHelp.

У них локализации-то своей нет, всё пользователями пишется. Есть автопереведённые статьи с соответствующей плашкой, есть переведённые вручную, обычно неактуальные.

Студенты у меня попадались на незнании используемых ими же функций из stdlib (те же rand/srand). Потом при мне заходили на неактуальную или автопереведённую статью, ничего не понимали. Потом по моему совету шли на английскую версию, читали и переводили вслух, получалось не очень =)

Закончилось домашним заданием на перевод нескольких статей.

Традиционные методы перевода не подходят для статей документации, потому что там всё связано и на отдельные строки не бьётся, построить итеративный процесс перевода не получится.

Но в любом случае, если хранить документацию в каком-то семантическом формате типа Markdown в git-репозитории, то она потом легко переводится и относительно легко проверяется её актуальность через сравнение даты изменений двух файлов, en и ru например (только всякие коммиты типа fixed typo могут помешать).

Написать скрипт для экспорта целой базы документов в markdown в любой формат публикации (qch, odt, pdf) несложно, потому что формат markdown описывает семантику содержимого, а не способ его отображения.

sphinx-doc умеет переводить стандартным gettext (http://sphinx-doc.org/latest/intl.html) + для опенсорса можно выложить бесплатно на https://www.transifex.com/ и делать это коллективно.

Для QtHelp есть команда конвертации:

$ make qthelp 
sphinx-build -b qthelp -d _build/doctrees   . _build/qthelp

Для описания C++ классов, функций и пр. есть http://breathe.readthedocs.org/ (можно писать комменты в rst разметке)

/*!
Inserting additional reStructuredText information.

\rst

This is some funky non-xml compliant text: <& !><

:ref:`install`

.. note::

   This reStructuredText has been handled correctly.
\endrst

*/

Про автоперевод согласен, как и про ручной. Но, вопрос в том сохраняется ли остальная обвязка, форматирование и т.д. или статья пишется заново на другом языке (как в википедии например).

Markdown никак не решает такую проблемму, т.к. блоки текста, ссылки и прочие части документа не имеют id'a, т.е. по факту, при локализации статью придётся писать заного, в лучшем случае методом научного копипаста.

Хорошее средство документации с поддержкой локализации позволит хранить разметку(markup) отдельно от содержимого(content). Естественно, количество деталей в разметке должно быть сниженно хотя бы до уровня markdown.

markdown описывает семантику содержимого, а не способ его отображения

Это не совсем верно. Более того, само название языка говорит «я про разметку». Помимо хуманридабельности markdown по классу решения практически ничем не отличается от html. Всего лишь больше деталей отдаётся на откуп рендереру.

Решение предложенное товарищем uralbash, может быть несомненно примененно и к markdown и к html, при условии, что тул гарантированно будет обходить ast набора документов всегда в одном порядке, тогда он может самостоятельно выдать им id'шники на которые пользователь и/или инструмент будут ссылаться в процессе перевода. Но для этого, скорее всего, придётся предпринять ряд усилий.

Но раз есть готовое решение, возможно имеет смысл опробовать именно его.

Очень интересный набор инструментов. Утащил в закладки ^_^

тогда он может самостоятельно выдать им id'шники на которые пользователь и/или инструмент будут ссылаться в процессе перевода.

В том же Qt id'шники - это английский текст, такие id не будут меняться при повторном парсинге.

Звучит логично. Но неудобно.

Если исправить офрографическую ошибку или пунктуацию - текст поменяется, а перевод, а точнее все ноды из всех переводов, станут ссылаться вникуда.

В итоге, нужно проверять «процент перведённости» после каждой сборки и подчищать мусор. Неговоря уже о том, что бы перепереводидить на все поддерживаемые языки незначительно изменившийся участок (возможно не требующий правки даже).

Я бы допустил хранить контрольную сумму текста как индикатор изменения и сигнализацию о том, что перевод возможно неактуален, но не более того. Уникальный ключ как таковой таки должен быть, как мне представляется.

Я думаю что на уровне moc таки делается что то более осознанное чем использование текста как ключа. Иначе не понятно как решается вышеописанная проблема.

не понятно как решается вышеописанная проблема

ПОтом и кровью.

До некоторой степени может помогать нечеткое сопоставление при обновлении перевода...

ПОтом и кровью.

Это шютка юмора, или ты достоверно вкурсе как оно реализованно?

нечеткое сопоставление при обновлении перевода

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

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

Вот где-то на стыке этих двух подходов должен быть правильный путь к локализации.

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

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

Даже соглашение о перемещении всех строк в ресурсы в оффтопик проекте может вызвать изрядный батхерт у неофита.

Не удержался, почитал доку.

Не понял, как решается ситуация когда tr() используется в такой форме:

QString some_free_function() {
    return QObject::tr("Whooups");
}

Конечно QCoreApplication::translate слегка улучшает положение дел, но одна фигня не очень однозначно выходит.

Получается любая Qt софтина с историей потенциально содержит n единиц мусора в своих файлах перевода.

Интересно, а как организован сей процесс в gtk?

Даже соглашение о перемещении всех строк в ресурсы в оффтопик проекте может вызвать изрядный батхерт у неофита.

Ресурсы так себе, у нас в оффтоп-проекте используется самописная Qt-подобная система перевода.

P.S. И мусор там так и остаётся в виде unused переводов, просто самописный gui-переводик позволяет их отфильтровать.

Нет в мире совершенства.

Ну, видимо на практике оно(изменения и наличие мусора) и не особо стреляет.