[Interest] Building Qt documentation as DITA

Fri Sep 19 16:53:11 CEST 2014

Hello.

Thank you for your answer, I was able to write a script that generates the
HTML documentation! (I plan to release it as open source when the project
is a bit more advanced, in case it's useful for someone else.) The bunch of
files that are generated seem to be coherent and quite complete (there's an
index page for the documentation, every module, then files for classes,
etc.). For the DITA part, I understood I should rewrite the .qdocconf files
to output DITA files (similar to what Qt Multimedia already has:
https://github.com/qtproject/qtmultimedia/tree/dev/src/multimedia/doc), but
I still have to investigate this.

However, when building the documentation with -log-progress, I see strange
things. First during the preparation, QDoc tries to load many index files,
while it shoud not (as per
https://bugreports.qt-project.org/browse/QTBUG-27707):

> ['C:/Qt/5.3/mingw482_32/bin/qdoc.exe', '-outputdir',
> 'C:/Qt/_script/html/qtcore/', '-installdir', 'C:/Qt/_script/html/',
> 'C:/Qt/5.3/Src/qtbase/src/corelib/doc/qtcore.qdocconf', '-prepare',
> '-indexdir', 'C:/Qt/_script/html/', '-no-link-errors', '-log-progress']
> LOG: Running qdoc for QtCore in -prepare mode
> LOG: Loading index file: C:/Qt/_script/html/qtdbus/qtdbus.index
> LOG: Loading index file: C:/Qt/_script/html/qmake/qmake.index
> LOG: Writing index file: C:/Qt/_script/html/qtcore//qtcore.index
> ['C:/Qt/5.3/mingw482_32/bin/qdoc.exe', '-outputdir',
> 'C:/Qt/_script/html/qtandroidextras/', '-installdir',
> 'C:/Qt/_script/html/',
> 'C:/Qt/5.3/Src/qtandroidextras/src/androidextras/doc/qtandroidextras.qdocconf',
> '-prepare', '-indexdir', 'C:/Qt/_script/html/', '-no-link-errors',
> '-log-progress']
> LOG: Running qdoc for QtAndroidExtras in -prepare mode
> LOG: Loading index file: C:/Qt/_script/html/qtcore/qtcore.index
> LOG: Writing index file:
> C:/Qt/_script/html/qtandroidextras//qtandroidextras.index

This shows some dependency between the modules when building the indexes…
Would it be a problem if I started the -prepare commands in parallel? I see
no reason why I could not, but this log puzzles me… (The whole process
takes quite a while, and it would be an interesting way of doing things
faster.)

When generating, QDoc shows many warnings, mainly for Qt Quick:

> ['C:/Qt/5.3/mingw482_32/bin/qdoc.exe', '-outputdir',
> 'C:/Qt/_script/html/qtquick/', '-installdir', 'C:/Qt/_script/html/',
> 'C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/qtquick.qdocconf', '-generate',
> '-indexdir', 'C:/Qt/_script/html/', '-no-link-errors', '-log-progress']
> LOG: Running qdoc for QtQuick in -generate mode
> LOG: Loading index file: C:/Qt/_script/html/qtcore/qtcore.index
> LOG: Loading index file:
> C:/Qt/_script/html/qtxmlpatterns/qtxmlpatterns.index
> LOG: Loading index file: C:/Qt/_script/html/qtqml/qtqml.index
> LOG: Loading index file: C:/Qt/_script/html/qtgui/qtgui.index
> LOG: Loading index file: C:/Qt/_script/html/qtlinguist/qtlinguist.index
> LOG: Loading index file:
> C:/Qt/_script/html/qtquickcontrols/qtquickcontrols.index
> LOG: Loading index file:
> C:/Qt/_script/html/qtquicklayouts/qtquicklayouts.index
> LOG: Loading index file: C:/Qt/_script/html/qtdoc/qtdoc.index
> LOG: Loading index file:
> C:/Qt/_script/html/qtquickdialogs/qtquickdialogs.index
> LOG: Loading index file: C:/Qt/_script/html/qtsensors/qtsensors.index
> LOG: Loading index file: C:/Qt/_script/html/qtwidgets/qtwidgets.index
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/advtutorial.qdoc:409:
> warning: Unable to parse JavaScript: "Syntax error" at line 2, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/advtutorial.qdoc:411:
> warning: Unable to parse JavaScript: "Syntax error" at line 2, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/advtutorial.qdoc:419:
> warning: Unable to parse JavaScript: "Syntax error" at line 2, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/advtutorial.qdoc:438:
> warning: Unable to parse JavaScript: "Syntax error" at line 2, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/concepts/input/textinput.qdoc:65:
> warning: This qdoc comment contains no topic command (e.g., '\module',
> '\page').
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/concepts/statesanimations/animations.qdoc:299:
> warning: This qdoc comment contains no topic command (e.g., '\module',
> '\page').
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/concepts/statesanimations/animations.qdoc:307:
> warning: This qdoc comment contains no topic command (e.g., '\module',
> '\page').
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/concepts/statesanimations/animations.qdoc:315:
> warning: This qdoc comment contains no topic command (e.g., '\module',
> '\page').
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/qmltypereference.qdoc:50:
> warning: Unable to parse QML snippet: "Expected token `numeric literal'" at
> line 2, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/context2d/qquickcanvasitem.cpp:726:
> warning: Invalid syntax in '\qmlmethod'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickitem.cpp:4095: warning:
> Ignored '\overload'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickitem.cpp:5822: warning:
> Cannot find 'QQuickItem::pos' specified with '\property' in any header file
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickwindow.cpp:2845:
> warning: Cannot find 'closing(...)' in '\fn' void QQuickWindow::closing()
>     [I cannot find any function of that name with the specified signature.
> Make sure that the signature is identical to the declaration, including
> 'const' qualifiers.]
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickwindow.cpp:3606:
> warning: Missing property type for Window::active
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.cpp:376:
> warning: Class RenderState has no \inmodule command; using project name by
> default: QtQuick
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp:74:
> warning: Cannot find 'setToplevelOpacity(...)' in '\fn' void
> QSGNodeUpdater::setToplevelOpacity(qreal opacity)
>     [I cannot find any function of that name with the specified signature.
> Make sure that the signature is identical to the declaration, including
> 'const' qualifiers.]
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp:85:
> warning: Cannot find 'toplevelOpacity(...)' in '\fn' qreal
> QSGNodeUpdater::toplevelOpacity() const
>     [I cannot find any function of that name with the specified signature.
> Make sure that the signature is identical to the declaration, including
> 'const' qualifiers.]
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/util/qsgsimplerectnode.cpp:47:
> warning: Class QSGSimpleRectNode has no \inmodule command; using project
> name by default: QtQuick
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/util/qsgtextureprovider.cpp:46:
> warning: Class QSGTextureProvider has no \inmodule command; using project
> name by default: QtQuick
> C:/Qt/5.3/Src/qtdeclarative/src/quick/util/qquicktransition.cpp:444:
> warning: Cannot find file to quote from: 'qml/dynamicscene/dynamicscene.qml'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/util/qquicktransition.cpp:444:
> warning: Unable to parse QML snippet: "Expected token `numeric literal'" at
> line 1, column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/util/qquicktransition.cpp:444:
> warning: Unexpected '\snippet (//! [top-level transitions])'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickitem.cpp:1803: warning:
> Undocumented enum item 'ItemAntialiasingHasChanged' in
> QQuickItem::ItemChange
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickitem.cpp:4110: warning:
> No documentation for 'QQuickItem::forceActiveFocus()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickitem.cpp:4128: warning:
> No documentation for 'QQuickItem::forceActiveFocus()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquicktextdocument.cpp:74:
> warning: No documentation for 'QQuickTextDocument::QQuickTextDocument()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquicktextdocument.cpp:83:
> warning: No documentation for 'QQuickTextDocument::textDocument()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquickwindow.h:151: warning:
> No documentation for 'QQuickWindow::closing()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.cpp:184:
> warning: No documentation for 'QSGMaterialShader::QSGMaterialShader()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.cpp:458:
> warning: No documentation for
> 'QSGMaterialShader::RenderState::devicePixelRatio()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/coreapi/qsgnode.cpp:106:
> warning: Undocumented enum item 'DirtySubtreeBlocked' in
> QSGNode::DirtyStateBit
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/util/qsgtextureprovider.h:54:
> warning: No documentation for 'QSGTextureProvider::texture()'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/scenegraph/util/qsgtextureprovider.h:57:
> warning: No documentation for 'QSGTextureProvider::textureChanged()'
> C:/Qt/5.3/Src/qtdeclarative/src/quickwidgets/qquickwidget.cpp:992:
> warning: No documentation for 'QQuickWidget::focusInEvent()'
> C:/Qt/5.3/Src/qtdeclarative/src/quickwidgets/qquickwidget.cpp:998:
> warning: No documentation for 'QQuickWidget::focusOutEvent()'
> qdoc: warning: Unable to parse JavaScript: "Syntax error" at line 41,
> column 1
> qdoc: warning: Unable to parse JavaScript: "Syntax error" at line 1,
> column 1
> qdoc: warning: Unable to parse JavaScript: "Syntax error" at line 42,
> column 1
> qdoc: warning: Unable to parse JavaScript: "Syntax error" at line 1,
> column 1
> qdoc: warning: Unable to parse JavaScript: "Syntax error" at line 2,
> column 1
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquicktranslate.cpp:469:
> warning: This page title exists in more than one file: "matrix4x4()"
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/qmltypereference.qdoc:925:
> warning: [It also exists here]
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/qquicktranslate.cpp:469:
> warning: This page title exists in more than one file: "matrix4x4()"
> C:/Qt/5.3/Src/qtdeclarative/src/quick/doc/src/qmltypereference.qdoc:925:
> warning: [It also exists here]
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/context2d/qquickcanvasitem.cpp:743:
> warning: No documentation for 'Canvas::getContext'
> C:/Qt/5.3/Src/qtdeclarative/src/quick/items/context2d/qquickcontext2d.cpp:2194:
> warning: Missing image: qml-item-canvas-arc.png

Does that indicate any problem in my workflow (I started from the sources
downloaded by the SDK)? Or are those errors due to mistakes in the source
codes (and thus shall be reported on Jira)?

Regards,
Thibaut Cuvelier

On 15 September 2014 16:56, Sze Howe Koh <szehowe.koh at gmail.com> wrote:

> On 15 September 2014 22:09, Thibaut Cuvelier <dourouc05 at gmail.com> wrote:
> > Hello.
> >
> > As advised on the forums (
> https://qt-project.org/forums/viewthread/47384/),
> > I'm cross-posting my question on this mailing list.
> >
> > In order to revive a Qt documentation translation, I would need to
> generate
> > Qt’s documentation as DITA files, which would be much easier to use than
> our
> > current solution (based on HTML files, whose structure is prone to
> > evolution, without having much meaning, as opposed to DITA). I would need
> > this output for Qt 4.6 up to the latest Qt 5.
> >
> > However, I’m unable to generate the whole documentation. Using the QDoc’s
> > documentation
> > (http://doc-snapshot.qt-project.org/qdoc/21-3-qt-dita-xml-output.html),
> I
> > can turn sources into documentations, but it’s rather wrong: when
> starting
> > it in Qt Android Extras, it generates the documentation for Qt Core, but
> > nothing about Qt Android Extras… What I am doing, first trying to get
> some
> > HTMLdocumentation:
> >>
> >> C:\Qt\5.3\Src\qtandroidextras\src > qdoc -outputdir C:\Qt\_html\
> >> -installdir C:\Qt\_html\
> >> C:\Qt\5.3\Src\qtbase\src\corelib\doc\qtcore.qdocconf
> >
> >
> > I would prefer no Makefile: it has more dependencies when deployed on a
> > server (make, a C++ compiler for QMake, at the very least), but also
> > requires to run configure (which disables Enginio when there is no
> OpenSSL,
> > while its documentation should be generated). However, this is the only
> > documented way, it seems
> > (https://qt-project.org/wiki/Building_Qt_Documentation)…
> >
> > I had a look to the generated Makefiles, I understood the generation is a
> > two-stage process (first make the indexes so links can be made, then do
> the
> > actual generation), but so far I’m unable to reproduce it using a Python
> > script.
> >
> > I feel rather lost; could someone please explain me the general picture
> of
> > generating Qt’s documentation and the parameters to give QDoc to get the
> > full documentation? I found very little information about this on the
> Web…
> >
> > Another question: is the DITA part of QDoc working well enough? Mainly,
> is
> > the whole content output in the XML files, with correct tags (not mixing
> > every thing)? I remember that the Qt Developer Network (when it was
> called
> > that way) used this form of the documentation to generate the pages
> > (
> http://blog.qt.digia.com/blog/2011/06/15/the-qt-documentation-has-made-it-into-devnet/
> ),
> > but I'm unsure about its current state--is the generation still working
> that
> > way?
> >
> > Thank you in advance!
> >
> >
> > Thibaut Cuvelier
>
> Hi,
>
> I've never generated DITA output before and I don't know how well the
> feature works. Nonetheless, here's what I know about building (HTML)
> documentation:
>
> 1) Qt is split across many separate modules, but there are many doc
> cross-references between modules correctly. To build the
> documentation, all their dependencies need to be resolved -- I don't
> think you can build one module at a time.
>
> 2) HTML output is produced in two stages:
>     * First, `qdoc.exe -prepare` is run in all modules.
>     * After that, `qdoc.exe -generate` is run in all modules.
>
> 3) Aside from `-outputdir` and `-installdir`, there is also `-indexdir`.
>     * In your case, you would use `-indexdir C:/Qt/5.3/Src/qtbase/doc`
>
>
> I've attached my log from a recent build which was done using Qt's
> configure.bat script and Makefiles. It has been filtered to include
> only lines that contain "qdoc.exe". I didn't build all modules here,
> but the log should show you the steps required for a manual build.
>
>
> Regards,
> Sze-Howe
>
> P.S. Qt-based applications (including qdoc) prefer '/' as the path
> separator, even on Windows
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20140919/09c71aa9/attachment.html>