[Interest] Building Qt documentation as DITA

[Thibaut Cuvelier]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20140915/3906f944/attachment.html>