[Development] Doc: What still needs to be done from a documentation/examples perspective.
Hello all, What still needs to be done for the Qt 5.0 documentation/examples (feel free to add more): Documentation: - Verify the content of the current documentation. See the email from last week http://www.mail-archive.com/development@qt-project.org/msg05889.html - Modularize the remaining modules. QtBase is still in progress and a lot of other modules have not been touched yet. A combination of my email from earlier this year ( http://www.mail-archive.com/development@qt-project.org/msg03059.html ), the changes in qtbase/examples and qtdeclarative/src/quick/doc/qtquick.qdocconf will explain the process. It comes down to moving the docs for the examples to [module]examples/doc, adding a qdocconf to [module]/src/[module]/doc and using the correct relative paths. - Make it possible to use global stylesheet images for all modules (QDoc problem). The modular documentation stylesheet wants to use some icons for things like previous and next page. These do not currently work and there does not currently seem to be a way to make them work with the global stylesheet, because of the relative paths that are used by the qdocconf files - make install targets for the modular documentation. The built documentation needs to be copied from [moduledir]/doc to $(QT_INSTALL_DOCS) - Verification that the Qt DevNet can handle a modularized documentation package. The DevNet currently uses the monolithic documentation build from the qtdoc module, if we would want to switch to the modularized way of building documentation the DevNet also needs to be able to handle that. - Fix QDoc errors There is some progress with a QDoc sanity bot which should lower the inflow of new errors, the current errors should also be fixed. Examples: - Develop a Qt demo Launcher that can also be used for QtQuick 2 examples. The code of the Qt4 qtdemo application is in the qttools repository, but that application does not support Qt Quick 2 examples, which makes it less useful for Qt 5. - Verify if the examples are still useful and showing the best usage of an API. There are also still discussions about doing a multi-pass qdoc run to link modular documentation bi-directionally. A make target for this should (probably) be added to qt5.git, so that a user does not have to go back and forth between modules to run some form ofmake docs. I have decided to not be part of the Qt transition from Nokia to Digia, but will keep being the maintainer for documentation (not full-time) and will not have time to finish all of these tasks. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] FYI: Better usage of the global qdocconf in qtbase
(Since there are so many people working on the documentation now I thought it'd be okay to use the list). I created https://codereview.qt-project.org/#change,33974 to make the global qdocconf in qtbase more useful (and minimize duplication). This change assumes that -installdir will always be specified when building modular documentation (e.g. use make docs). I think we should also put all of the qdoc defines in one central file, but that'll come later. Probably we will need an *-online-templates soon, since I am working on a simple search system for the Qt5 documentation (non-DevNet, so only the snapshot and when you build the docs yourself). Casper P.S. I would like to thank everybody for helping out with the docs! ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Request: Mark classes with \module in documentation
On Thu, Aug 23, 2012 at 07:30:23AM +, ext casper.vandonde...@nokia.com wrote: example: /*! \class QObject \inmodule QtCore ... */ isn't it a *tad* weird that sources in a modularized package need to declare in which package they are, several hundred times? i call that suboptimal (i'm apparently having a nice day). Maybe not optimal but given the option of doing this or extensive hacking in qdoc it's probably the pragmatic solution for now :) What I want to do in QDoc is to automatically set the module to the value of the project variable in the qdocconf file (if no \inmodule command is specified). This means that currently around 80% of the classes in the monolithic build would suddenly belong to the Qt module. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] How to build Qt5's docs?
On Tue, Aug 21, 2012 at 9:03 AM, Alan Ezust alan.ez...@gmail.com wrote: The issue is that in the doc/html/qt.qhp file, on line 14348, is an xml element with a ref=. This is the problem I was having. What is interesting to know is what is on that line? And I bet you it is QDeclarativeImageProvider. Sorry, I meant to say QImageCleanupFunction here. Ah, I thought we had fixed that one. Cherry-picking https://codereview.qt-project.org/#change,33187 will make qhelpgenerator just generate a warning and not stop processing. A consequence is that you cannot search for the missing ref= items in the documentation, but at least it gets generated. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Change of QDoc command from \qmlclass to \qmltype
Hi, Tasks for the doc team: -implement change in QDoc, but gracefully deprecate the \qmlclass by giving a warning about using \instantiates instead. -go through the modules and change the documentation. Notify the maintainer. -send email to the affected maintainers. Just to be clear: the doc team is undefined, everybody in the community is welcome to help. (and if you are developing your own set of components you will have to change the commands anyway if you are using QDoc. If you are interested to learn how QDoc works this would be the time to step up. Notifying the maintainers is obviously not really necessary, since this mailing list serves part of that purpose. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Can we bring back QT += declarative?
On 7/19/12 12:40 PM, Knoll Lars (Nokia-MP/Oslo) lars.kn...@nokia.com wrote: On 6/29/12 11:37 PM, ext Thiago Macieira thiago.macie...@intel.com wrote: On quinta-feira, 28 de junho de 2012 23.53.51, martin.jo...@nokia.com wrote: Reassigning declarative back to qtquick1 could be done. I'm not sure that is an improvement since we have QtQuick 2 in the qtdeclarative module, so it actually becomes more confusing. And the Qt Quick 2 library is called QtDeclarative. How about we do a swap- around and rename the Qt Quick 1 library back to QtDeclarative (its API is QDeclarativeXXX anyway) and we rename the Qt Quick 2 library to libQtQuick2? The Qt Quick 2 lib is called libQtQuick, not QtDeclarative. We could rename the old lib back, but I'm not sure it's worth it. Making QT += declarative work and link against libQtQuick1 should be enough. What do we want to do in the examples in that case? Can we there still use QT += qtquick1? For people that are new to Qt using QT += declarative might confuse them that they are using something that is not in the qtdeclarative folder (and that they are using an add-on instead of an essential, even though the name of the essential git repo is qtdeclarative) Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Qt5 beta, MinGW: undefined reference to `WinMain@16'
Hi,
Which GCC is this (both for w32 and w64)? For KDE I tried to use 4.6.4 and we
are having a lot of problems with that, so we are now waiting for a patched GCC
4.7.x
Casper
From: ext Loaden loa...@gmail.commailto:loa...@gmail.com
Date: Wednesday, July 11, 2012 3:52 PM
To: shane.kea...@accenture.commailto:shane.kea...@accenture.com
shane.kea...@accenture.commailto:shane.kea...@accenture.com
Cc: development@qt-project.orgmailto:development@qt-project.org
development@qt-project.orgmailto:development@qt-project.org
Subject: Re: [Development] Qt5 beta, MinGW: undefined reference to `WinMain@16'
Does anyone care about mingw support?
It's an qt5 issue, or an mingw issue?
I don't sure anything, but it's real noise!
Because I can't corss build for Windows use Qt5 now.
http://sourceforge.net/tracker/?func=detailatid=983354aid=3539247group_id=202880
2012/7/6 Loaden loa...@gmail.commailto:loa...@gmail.com
I just create a bug report, and hope someone can take of.
It's only Qt5 issue, Qt4 works well!!
2012/7/5 Loaden loa...@gmail.commailto:loa...@gmail.com
Yes, same problem happened when using qmake.
for qbs, I made a patch for link to static library, see:
https://codereview.qt-project.org/#change,29232
2012/7/5 shane.kea...@accenture.commailto:shane.kea...@accenture.com
Does the same problem happen if using qmake instead of qbs?
There is a qtmain.lib static library that should be added automatically to
windows executables, which provides the WinMain entry point.
--
From:
development-bounces+shane.kearns=accenture@qt-project.orgmailto:accenture@qt-project.org
[mailto:development-bounces+shane.kearnsmailto:development-bounces%2Bshane.kearns=accenture@qt-project.orgmailto:accenture@qt-project.org]
On Behalf Of Loaden
Sent: 05 July 2012 04:15
To: development
Subject: [Development] Qt5 beta, MinGW: undefined reference to `WinMain@16'
main.cpp
#include QCoreApplication
int main(int argc, char **argv)
{
QCoreApplication app(argc, argv);
return app.exec();
}
test.qbp
import qbs.base 1.0
Application {
name : Test
Depends {
name: Qt.widgets
}
files : [
main.cpp
]
}
MinGW-TDM32:
Found project file D:\qpSOFT\Projects\Test\test.qbp
loading project took: 79 ms
build graph took: 14 ms
for t86-tdm-mingw32-release:
- [hpp, application] Test as t86-tdm-mingw32-release
compiling main.cpp
linking Test.exe
D:\qpSOFT\MinGW\TDM-MinGW32\bin/g++ -O2 -Wall -W
D:/qpSOFT/Projects/Test/build/t86-tdm-mingw32-relea
se/.obj/Test/main.o -o
D:/qpSOFT/Projects/Test/build/t86-tdm-mingw32-release/Test.exe -LD:/qpSOFT/Pr
ojects/BuildQt5-t86/qtbase/lib -lqtmain -lQtCore5 -lQtGui5 -lQtWidgets5
d:/qpsoft/mingw/tdm-mingw32/bin/../lib/gcc/mingw32/4.6.1/../../../libmingw32.a(main.o):
In function
`main':
C:\MinGW\msys\1.0\src\mingwrt/../mingw/main.c:73: undefined reference to
`WinMain@16'mailto:%60WinMain@16%27
collect2: ld returned 1 exit status
MinGW-w64
D:\qpSOFT\MinGW\MinGW32\bin/g++ -m32 -O2 -Wall -W
D:/qpSOFT/Projects/Test/build/m86-mingw32-release/
.obj/Test/main.o -o D:/qpSOFT/Projects/Test/build/m86-mingw32-release/Test.exe
-LD:/qpSOFT/Projects/
BuildQt5-m86/qtbase/lib -lqtmain -lQtCore5 -lQtGui5 -lQtWidgets5
d:/qpsoft/mingw/mingw32/bin/../lib/gcc/i686-w64-mingw32/4.6.3/../../../../i686-w64-mingw32/lib/../li
b/libmingw32.a(lib32_libmingw32_a-crt0_c.o): In function `main':
/home/ruben/mingw-w64/toolchain/src/mingw-w64/tags/v2.0.3/mingw-w64-crt/crt/crt0_c.c:18:
undefined r
eference to `WinMain@16'mailto:%60WinMain@16%27
collect2: ld returned 1 exit status
--
Please don't ask where I come from, It's a shame!
Best Regards
Yuchen
Subject to local law, communications with Accenture and its affiliates
including telephone calls and emails (including content), may be monitored by
our systems for the purposes of security and the assessment of internal
compliance with Accenture policy.
__
www.accenture.comhttp://www.accenture.com/
--
Please don't ask where I come from, It's a shame!
Best Regards
Yuchen
--
Please don't ask where I come from, It's a shame!
Best Regards
Yuchen
--
Please don't ask where I come from, It's a shame!
Best Regards
Yuchen
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Proposal: Remove QML from Qt's code base (OR: Should it be a requirement that Qt Modules are interoperable?)
The modularization system already gives you this ability. If you do not build the qtdeclarative module, it will not install itself in the mkspecs/modules directory under QT_INSTALL_PATH and will not be available as modules. .pro files can check for the availability of a certain module and include/exclude files based on that or otherwise adapt the build of that particular module. I'm sure there quite a few places where this check could be added in the dependent modules, but it should be doable to fix those one by one as they come up. So that is possible. QtQuick3D for example just does: QT = core gui qml quick 3d and there is no check anywhere in that repo that checks if QML should be built, so you get an error about missing qml and quick modules. I wouldn't mind fixing it, but I just missed how you can check for this stuff (and a quick Google does not find it). Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] doc: need rename qdoc3 - qdoc
Hi, First of all: the monolithic build in qtdoc will be removed once all modules contain their own make docs target, since that monolithic build does not allow the same filename in any module, in the future each module should probably have a page with: /*! \title [libraryname] index \page index.html */ Then you can link to the module index from any other module that depends on it. The blue and white stylesheet is the new offline style that we also use for Creator (blue is better than green for colorblind people apparently), I have not had the time yet to put an online style in place (and I don't know yet how we want to support the current online style, since some of the side-menu entries use downstream linking and are hard-coded in the HTML pages themselves). Casper From: Blasche Alex (Nokia-MP/Brisbane) Sent: Friday, June 22, 2012 6:42 AM To: Vandonderen Casper (Nokia-MP/Oslo); development@qt-project.org Subject: RE: [Development] doc: need rename qdoc3 - qdoc Hi, How is this individual module generation supposed to tie into the global doc generation which kind of still works by going into qtdoc and running make docs? Or isn't there a hook? Also it seems that qtbase uses once again a completely new stylesheet set (blue and white). I would really appreciate a bit more information than the snippet above. -- Alex -Original Message- From: development-bounces+alex.blasche=nokia@qt-project.org [mailto:development-bounces+alex.blasche=nokia@qt-project.org] On Behalf Of Vandonderen Casper (Nokia-MP/Oslo) Sent: Monday, 4 June 2012 18:27 To: loa...@gmail.com; development@qt-project.org Subject: Re: [Development] doc: need rename qdoc3 - qdoc Hi, Technically this structure should not be used at all anymore, but rather the auto-magic we introduced. The preferred way is to specify QMAKE_DOCS = [qdocconf file], this will automatically set up a make docs target for this module. Casper From: ext Loaden loa...@gmail.com Date: Sunday, June 3, 2012 6:00 AM To: development development@qt-project.org Subject: [Development] doc: need rename qdoc3 - qdoc See the diff show below. Any comments? Entering 'qlalr' Entering 'qt3d' Entering 'qtactiveqt' Entering 'qtbase' Entering 'qtconnectivity' diff --git a/doc/doc.pri b/doc/doc.pri index 459e9ba..3cd0b30 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -3,10 +3,10 @@ OTHER_FILES += \ $$PWD/qt5-dita.qdocconf docs_target.target = docs -docs_target.commands = qdoc3 $$PWD/qt5.qdocconf +docs_target.commands = qdoc $$PWD/qt5.qdocconf ditadocs_target.target = ditadocs -ditadocs_target.commands = qdoc3 $$PWD/qt5-dita.qdocconf +ditadocs_target.commands = qdoc $$PWD/qt5-dita.qdocconf QMAKE_EXTRA_TARGETS = docs_target ditadocs_target QMAKE_CLEAN += \ Entering 'qtdeclarative' diff --git a/doc/config/qtdeclarative_doc.pri b/doc/config/qtdeclarative_doc.pri index 51f2fce..d8a3a33 100644 --- a/doc/config/qtdeclarative_doc.pri +++ b/doc/config/qtdeclarative_doc.pri @@ -2,12 +2,12 @@ OTHER_FILES += \ $$PWD/qtquick.qdocconf \ $$PWD/qtquick-dita.qdocconf -online_docs.commands = qdoc3 $$PWD/qtquick.qdocconf +online_docs.commands = qdoc $$PWD/qtquick.qdocconf -dita_docs.commands = qdoc3 $$PWD/qtquick-dita.qdocconf +dita_docs.commands = qdoc $$PWD/qtquick-dita.qdocconf docs.depends = dita_docs online_docs QMAKE_EXTRA_TARGETS = docs dita_docs online_docs QMAKE_CLEAN += \ -r $$PWD/html \ - -r $$PWD/ditaxml \ No newline at end of file + -r $$PWD/ditaxml Entering 'qtdoc' Entering 'qtdocgallery' Entering 'qtfeedback' Entering 'qtgraphicaleffects' Entering 'qtimageformats' diff --git a/doc/doc.pri b/doc/doc.pri index e87ab19..3e401df 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -3,10 +3,10 @@ OTHER_FILES += \ $$PWD/qtimageformats-dita.qdocconf docs_target.target = docs -docs_target.commands = qdoc3 $$PWD/qtimageformats.qdocconf +docs_target.commands = qdoc $$PWD/qtimageformats.qdocconf ditadocs_target.target = ditadocs -ditadocs_target.commands = qdoc3 $$PWD/qtimageformats- dita.qdocconf +ditadocs_target.commands = qdoc $$PWD/qtimageformats- dita.qdocconf QMAKE_EXTRA_TARGETS = docs_target ditadocs_target QMAKE_CLEAN += \ Entering 'qtjsbackend' Entering 'qtjsondb' Entering 'qtlocation' diff --git a/doc/config/qtlocation_doc.pri b/doc/config/qtlocation_doc.pri index a2e2bab..feae9eb 100644 --- a/doc/config/qtlocation_doc.pri +++
Re: [Development] Make qdoc an officially supported tool for generating QML API documentation
Hi, We have been very busy to get qdoc running outside of Qt (I am starting to use qdoc as LaTeX-lite now if I just need an HTML page). I do agree that the qdoc manual should be improved with examples that do not necessarily reflect how we use qdoc with Qt. All changes that we are doing to qdoc are only added to the Qt5 version of qdoc (which is qdoc instead of qdoc3). The Qt5 version should also support the \inherits you mentioned in the QTBUG (be aware that you cannot use \inherits when documenting .qml files, since we automatically use the top level element in the .qml file. Casper On 6/8/12 5:16 PM, ext Sven Anderson sven.ander...@snom.com wrote: Hi all, since qdoc is the only tool that can create documentation for QML APIs, but it's (AFAIK) not supported as an external tool - although that is very much needed especially for QML - I suggest to make qdoc the offical tool for generation of external QML API documentation (and fix it accordingly). I filed a suggestion here: https://bugreports.qt-project.org/browse/QTBUG-26096 Best regards, Sven ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] doc: need rename qdoc3 - qdoc
Hi,
Technically this structure should not be used at all anymore, but rather the
auto-magic we introduced.
The preferred way is to specify QMAKE_DOCS = [qdocconf file], this will
automatically set up a make docs target for this module.
Casper
From: ext Loaden loa...@gmail.commailto:loa...@gmail.com
Date: Sunday, June 3, 2012 6:00 AM
To: development development@qt-project.orgmailto:development@qt-project.org
Subject: [Development] doc: need rename qdoc3 - qdoc
See the diff show below.
Any comments?
Entering 'qlalr'
Entering 'qt3d'
Entering 'qtactiveqt'
Entering 'qtbase'
Entering 'qtconnectivity'
diff --git a/doc/doc.pri b/doc/doc.pri
index 459e9ba..3cd0b30 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -3,10 +3,10 @@ OTHER_FILES += \
$$PWD/qt5-dita.qdocconf
docs_target.target = docs
-docs_target.commands = qdoc3 $$PWD/qt5.qdocconf
+docs_target.commands = qdoc $$PWD/qt5.qdocconf
ditadocs_target.target = ditadocs
-ditadocs_target.commands = qdoc3 $$PWD/qt5-dita.qdocconf
+ditadocs_target.commands = qdoc $$PWD/qt5-dita.qdocconf
QMAKE_EXTRA_TARGETS = docs_target ditadocs_target
QMAKE_CLEAN += \
Entering 'qtdeclarative'
diff --git a/doc/config/qtdeclarative_doc.pri b/doc/config/qtdeclarative_doc.pri
index 51f2fce..d8a3a33 100644
--- a/doc/config/qtdeclarative_doc.pri
+++ b/doc/config/qtdeclarative_doc.pri
@@ -2,12 +2,12 @@ OTHER_FILES += \
$$PWD/qtquick.qdocconf \
$$PWD/qtquick-dita.qdocconf
-online_docs.commands = qdoc3 $$PWD/qtquick.qdocconf
+online_docs.commands = qdoc $$PWD/qtquick.qdocconf
-dita_docs.commands = qdoc3 $$PWD/qtquick-dita.qdocconf
+dita_docs.commands = qdoc $$PWD/qtquick-dita.qdocconf
docs.depends = dita_docs online_docs
QMAKE_EXTRA_TARGETS = docs dita_docs online_docs
QMAKE_CLEAN += \
-r $$PWD/html \
- -r $$PWD/ditaxml
\ No newline at end of file
+ -r $$PWD/ditaxml
Entering 'qtdoc'
Entering 'qtdocgallery'
Entering 'qtfeedback'
Entering 'qtgraphicaleffects'
Entering 'qtimageformats'
diff --git a/doc/doc.pri b/doc/doc.pri
index e87ab19..3e401df 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -3,10 +3,10 @@ OTHER_FILES += \
$$PWD/qtimageformats-dita.qdocconf
docs_target.target = docs
-docs_target.commands = qdoc3 $$PWD/qtimageformats.qdocconf
+docs_target.commands = qdoc $$PWD/qtimageformats.qdocconf
ditadocs_target.target = ditadocs
-ditadocs_target.commands = qdoc3 $$PWD/qtimageformats-dita.qdocconf
+ditadocs_target.commands = qdoc $$PWD/qtimageformats-dita.qdocconf
QMAKE_EXTRA_TARGETS = docs_target ditadocs_target
QMAKE_CLEAN += \
Entering 'qtjsbackend'
Entering 'qtjsondb'
Entering 'qtlocation'
diff --git a/doc/config/qtlocation_doc.pri b/doc/config/qtlocation_doc.pri
index a2e2bab..feae9eb 100644
--- a/doc/config/qtlocation_doc.pri
+++ b/doc/config/qtlocation_doc.pri
@@ -7,7 +7,7 @@ win32:!win32-g++ {
unixstyle = true
}
-QDOC = $$QT.core.bins/qdoc3
+QDOC = $$QT.core.bins/qdoc
ONLINE_CONF = $$PWD/qtlocation.qdocconf
DITA_CONF = $$PWD/qtlocation-dita.qdocconf
@@ -15,7 +15,6 @@ QCH_CONF = #nothing yet
$$unixstyle {
} else {
-QDOC = $$replace(QDOC, qdoc, qdoc3.exe)
ONLINE_CONF = $$replace(ONLINE_CONF, /, \\)
DITA_DOCS = $$replace(ONLINE_CONF, /, \\)
}
Entering 'qtmultimedia'
diff --git a/doc/config/qtmultimedia_doc.pri b/doc/config/qtmultimedia_doc.pri
index 8aab323..9f36439 100644
--- a/doc/config/qtmultimedia_doc.pri
+++ b/doc/config/qtmultimedia_doc.pri
@@ -7,15 +7,7 @@ win32:!win32-g++ {
unixstyle = true
}
-system(which qdoc) {
-QDOC = qdoc
-} else {
-exists($$QT.core.bins/qdoc3) {
-QDOC = $$QT.core.bins/qdoc3
-} else {
-warning(No qdoc executable found.)
-}
-}
+QDOC = $$QT.core.bins/qdoc
ONLINE_CONF = $$PWD/qtmultimedia.qdocconf
DITA_CONF = $$PWD/qtmultimedia-dita.qdocconf
@@ -23,7 +15,6 @@ QCH_CONF = #nothing yet
$$unixstyle {
} else {
-QDOC = $$replace(QDOC, qdoc, qdoc3.exe)
ONLINE_CONF = $$replace(ONLINE_CONF, /, \\)
DITA_DOCS = $$replace(ONLINE_CONF, /, \\)
}
Entering 'qtphonon'
Entering 'qtpim'
Entering 'qtqa'
Entering 'qtquick1'
Entering 'qtrepotools'
Entering 'qtscript'
Entering 'qtsensors'
diff --git a/doc/config/qtsensors_doc.pri b/doc/config/qtsensors_doc.pri
index 4c91758..9ce9913 100644
--- a/doc/config/qtsensors_doc.pri
+++ b/doc/config/qtsensors_doc.pri
@@ -7,7 +7,7 @@ win32:!win32-g++ {
unixstyle = true
}
-QDOC = $$QT.core.bins/qdoc3
+QDOC = $$QT.core.bins/qdoc
ONLINE_CONF = $$PWD/qtsensors.qdocconf
DITA_CONF = $$PWD/qtsensors-dita.qdocconf
@@ -15,7 +15,6 @@ QCH_CONF = #nothing yet
$$unixstyle {
} else {
-QDOC = $$replace(QDOC, qdoc, qdoc3.exe)
ONLINE_CONF = $$replace(ONLINE_CONF, /, \\)
DITA_DOCS = $$replace(ONLINE_CONF, /, \\)
}
Entering 'qtsvg'
Entering 'qtsystems'
Entering 'qttools'
Entering 'qttranslations'
Entering 'qtwayland'
Entering 'qtxmlpatterns'
diff --git a/.gitignore b/.gitignore
index 6e178a2..5cbefb5 100644
---
[Development] Examples: Move file/image list to bottom of file
Hi, Example: http://doc-snapshot.qt-project.org/5.0/mainwindows-application.html Currently we render the list of examples at the top of the page, as visible in the example. On that page you do not really get an idea about the example before scolling down (1280x800 resolution). Therefore I would like to move the list of files/images to the bottom of the page. Opinions? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Qt 5.0 beta and final timelines
In the meantime we can/should think about doing another alpha. Thiago proposed that one option here could be to simply release the first source package that works on all platforms as the second alpha. Like that we don't use any additional resources and time on creating that second alpha. Cheers, Lars I assume we would want qt5.git integration to happen first? That hasn't happened since April 18th, a lot of changes are still waiting for that to happen (I think all the Qurl/QRegExp) stuff etc. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] Documentation bug maintenance
Hi all, Thiago mentioned some time ago that all bugs that nobody is working on should be set to Unassigned. Therefore I would like to propose that the QTBUG Documentation component and QTWEBSITE doc.qt.nokia.com component set the assignee to Unassigned by default to allow anyone in the community to work on them. It seems like the Documentation component assignee is set to Qt Documentation Team and I think this is not valid anymore, unless we get a public mailing list where all of the bug emails for this user are sent to. The default assignee for doc.qt.nokia.com seems to be a user who does not work in the Qt Documentation Team anymore. I created the following JIRA dashboard: https://bugreports.qt-project.org/secure/Dashboard.jspa?selectPageId=11521 It lists most of the currently open bugs that are related to documentation (I'm not checking for things like docs since that might not be valid). There are almost 900 bugs there which should be triaged by the community. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] QtHelp Module
On 4/25/12 5:01 PM, ext Jordi Pujol pisoengra...@gmail.com wrote: Hi all, I'm trying to embed a context-sensitive help system to my app. And I wonder why QtHelp module was left in the middle :-( I'll try to explain : you create your fancy-shiny-great-rich html/css based documentation ( doxygen or similar ) and you put it in a qch file. Then, you want to use QHelpEngine co. to show the help embedded in yout app. Following an aged tutorial , you can embed in a form some widgets without too much effort. *BUT* QTextBrowser is not enough for you. You have to use QWebView to allow a richer subset of HTML. But QWebView doesn't understand url's like 'qthelp:// Well, don't panic, look at assistant sources to see how trolls made this : It's a bit a mess !! Do I have to repeat that code to have the same behaviour aspect ? So, looking at qtassistant's MainWindow.cpp I think that a generic help form can be added into QtHelp module to avoid reinventing the wheel for every Qt application. The idea is to have a class QHelpBrowser that can be simply inserted in any widget to have an embedded qtassistant. In assistant's code, main.cpp will remain the same and MainWindow.cpp could be split in two : the strictly MainWindow needed code ( cmd line parsing assistat's main form related stuff ) and a new class, shared with QtHelp module, that has all striclty related to help navigation stuff. Obviously, with the possibility to hide/show index, find, contents, etc. What do you think about this idea ? If you do not break the current functionality in Qt Creator / Qt Assistant: Go for it. Be aware that we are currently in feature freeze, so the first Qt release containing these changes will be Qt 5.1 Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Hi, I just cut out the rest of the email for clarity. (great that you would want to help) I just want to talk about the inherits and inherited by problem. Inherits should always work, because you compile the Qt code that way (you cannot subclass a class that doesn't exist yet). I just want to make clear that fixing the Inherited by problem without building all documentation in one go is not that easy. In theory it would be very easy: We would put the inherited by in a unique HTML element, for example: p class=inheritedby. That way we can open the file as a qdomdocument and replace that paragraph with a new list. We have said that documentation will get installed to QT_INSTALL_DOCS, which might be a folder which requires root write-access, in that case we would need to ask for the sudo password while qdoc is running to be able to re-write the inherited by list, which I think is also not feasible. Proposals for different approaches are always welcome of course. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] important: upcoming rename of _qpa.h to _p.h
Hi, On 4/18/12 4:03 PM, ext Girish Ramakrishnan gir...@forwardbias.in wrote: Since there's been no proposal, here's an alternate proposal: 1. We drop _qpa completely. So, it would become qplatformbackingstore.h 2. We teach syncqt that qplatform* is special and we move them all to a special qpa/ directory. So, instead of #include QtGui/private/qplatformbackingstore.h, it will be #include QtGui/qpa/qplatformbackingstore.h 3. We teach syncqt to create QtGui/QPA or #include QPA headers. (I think we need the latter since qpa headers are not restricted to gui) 4. We teach the world that qpa is not meant for apps. 5. Add a more benign header pointing out the fact that these files are qpa files. 6. Rename the handle() to platformXXX() since it's easy to educate that anything that has platform in it is out of reach of app developers. Just for my mental state of mind: will these classes then be documented as normal classes, or \internal, or do we need something special for them still? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] Removing the \compat QDoc command
Hi, We have multiple commands to mark documentation content as outdated: \deprecated, \obsolete and \compat. \compat was used for Qt3 compatibility. There are only 12 occurrences of \compat under qt5.git in the documentation, but none of that documentation actually gets printed. So please change the used command to \obsolete, or remove the QDoc comment, because this will give new QDoc errors once \compat is taken out of qdoc. The 12 locations of \compat outside of qdoc/the qdoc manual are: qtbase/src/printsupport/kernel/qprinter.cpp:373 qtbase/src/sql/kernel/qsql.qdoc:43 qtbase/src/sql/kernel/qsql.qdoc:54 qtbase/src/widgets/dialogs/qcolordialog.cpp:2005 qtbase/src/widgets/dialogs/qcolordialog.cpp:2010 qtbase/src/widgets/kernel/qapplication.cpp:3952 qtbase/src/widgets/kernel/qapplication.cpp:4050 qtbase/src/widgets/kernel/qapplication.cpp:4056 qtbase/src/widgets/widgets/qmenubar.cpp:1911 qtbase/src/widgets/widgets/qslider.cpp:540 qtbase/src/widgets/widgets/qslider.cpp:547 qtbase/src/widgets/widgets/qtextedit.cpp:2496 Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/13/12 7:34 AM, Lincoln Ramsay lincoln.ram...@nokia.com wrote: On 04/13/2012 03:19 PM, Vandonderen Casper (Nokia-MP/Oslo) wrote: But I would be grateful if you would make a plan on how to turn qdoc into a mini-qmake so that qdoc can parse the .pro/sync.profile, so that we don't need the depends. Because that would probably also mean that you have to run qdoc [module.pro] [module.qdocconf], or do you see that differently? Doesn't qmake run over doc.pri to generate a Makefile rule make docs that you run? Or are we moving away from make docs and towards running qdoc explicitly? You are correct, that is what will happen, the same as the current system. The thing is that people have difficulty understanding where QT_QML_QDOCCONF etc. come from currently. I can see a problem with this since for Qt QtCore is just called core, and I would not want to output the documentation to just /doc/core, but /doc/qtcore, since there might be modules that do not start with Qt and still use QDoc. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/13/12 10:32 AM, ext Oswald Buddenhagen
oswald.buddenha...@nokia.com wrote:
On Fri, Apr 13, 2012 at 07:04:42AM +, ext
casper.vandonde...@nokia.com wrote:
You are correct, that is what will happen, the same as the current
system.
The thing is that people have difficulty understanding where
QT_QML_QDOCCONF etc. come from currently.
I can see a problem with this since for Qt QtCore is just called core,
and
I would not want to output the documentation to just /doc/core, but
/doc/qtcore, since there might be modules that do not start with Qt and
still use QDoc.
big deal.
qdoc_deps =
for(m, QT): qdoc_deps += $$lower($$eval(QT.$${m}.name))
and all that should be centralized in qt_module_config.prf, where all
the module creation magic happens. a lot more is already pending for the
buildsystem branch.
you should ask the buildsystem guys a bit more often in advance instead
of complaining that they are complaining about your solutions. ;)
Ok, that will work for Qt C++ modules. If a user has a QML-only module we
still need to hard-code it in the .pri file then.
Casper
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
[Development] Towards a Qt 5 beta: Documentation
Hi everybody, TL;DR: We need to change the way Qt does documentation. A lot of things will change and we need help from everybody. As mentioned by Lars: We should make sure the quality of the documentation for Qt 5.0 is as high as possible. To get and keep our documentation in shape for Qt 5.0 and beyond I think we will need to tackle the following problems: 1. The documentation is not modularized. 2. The documentation build system is hard to explain to people. (consequence of 1) 3. The different Qt modules have a completely different style of documenting. 4. The QDoc commands and functionality are not known well enough by people, which causes QDoc errors. 5. There is no real review process for documentation contributions. Modularizing the documentation is a process that will move a lot of files around and make some things impossible. The biggest consequence will be that we will have the same dependency chain as when compiling the modules. E.g. not allow circular dependencies in the documentation. Therefore there can be no links from the QtGui documentation to any class in QtWidgets, from QtWidgets to QtGui will work, since Widgets depends on Gui. This will also automatically break Inherited by: between classes in separate modules in the documentation. I have written down a possible method for modularizing the documentation at the end of this email. That should make the whole process more transparent. Issue 3 just needs people to clean up the documentation, writing guidelines to get this standard will be published on the Qt Project Wiki. For issue 4 I would like to point people to http://doc-snapshot.qt-project.org/qdoc/ this is the URL of the qdoc manual. If everybody follows what is written there and reports bugs about inconsistencies in the manual we should have a minimal influx of new qdoc errors. There are problems in qdoc (like not understanding C++ templates/macros and C++11 syntax for documenting QObject::connect), but we should not start putting Doxygen documentation commands in QDoc when there is a QDoc equivalent. I am also aware that we still need to change a lot of old documentation, like replacing all \gui commands with \uicontrol, which is quite a simple search/replace. Issue 5 needs thought and help from everybody. We will keep the normal reviewing process for documentation and we cannot enforce all documentation patches to be reviewed by native English speakers/technical writers. But when documentation changes we should all pay special attention to making it understandable to someone who is new to Qt. This has always been the focus of the Qt documentation and I think we should try to keep the same standard of documentation going forward. -- Modularized documentation proposal Let's use qtbase as an example, since that needs the global content such as CSS and default qdocconfs. - Source code stays where it is now under /src. - Global documentation (such as CSS Files and default qdocconf templates) goes into /doc/global. This will be copied to QT_INSTALL_DOCS/global to be used by the other repositories. modules inside qtbase will use relative links to the /doc/global folder. - Individual modules have their documentation in /src/[conveniencename]/doc. For example: /src/corelib/doc. Documentation .qdoc files will stay under src in that folder, snippets will stay under snippets, etc. - Images will go in /src/[conveniencename]/doc/images, cross-module images will not be allowed (unless you copy them into multiple folders). - The [modulename].qdocconf will be in the top-level directory for the module. For QtCore this means that the qdocconf file will be qtbase/src/corelib/doc/qtcore.qdocconf. - Documentation output will be put in /doc/html/[modulename]. The whole /doc/html/[modulename] folder will be copied to QT_INSTALL_DOCS/[modulename] - For cross-linking we need to do a few things (None of this is implemented yet): 1. We need to add a depends qdocconf variable, where you list the modules you depend on. The easiest thing would be to use the full modulename, so qtcore instead of just core. This means that you put depends += qtcore in the qtgui.qdocconf 2. We could then implement an -indexdir CLI option/variable which points to the directory containing all documentation and let qdoc look for /[modulename]/[modulename].index under that folder, 3. Then we will have to set-up the .pri files to let indexdir point to qtbase/doc/html for the modules in qtbase and QT_INSTALL_DIR/doc for the other modules. So when building qtgui qdoc will be called with qdoc -indexdir doc/html doc/gui/qtgui.qdocconf. This should make it find /doc/html/qtcore/qtcore.index when you put depends += qtcore in the qtgui.qdocconf. 4. A problem will occur when you have other repositories that contain multiple modules. (such as qtpim and qtdeclarative) So there we need to specify 2 -indexdir options, QDoc should check the timestamp when there are 2 conflicting index files and use the newest one. - In
Re: [Development] Towards a Qt 5 beta: Documentation
While I understand the reasoning, I am not sure the limitations above are acceptable. At least, if I understand you correctly. I think that loosing all the cross links and all the inherited-by links that span modules is unaceptable. For instance, you would no longer be able to see relations between some major classes, like QObject - QWidget. You'd only be able to see QWidget - QObject. These kinds of links are not something that does not happen. The QObject docs are a good example of that, as they actually reference QWidget. Personally, I also regulary use the Inherited by list. I would hate to see that go. I don't have a solution ready though. I also don't like it. What is the benefit of doing that? what went wrong with make docs? There are 2 main problems with the current system: 1. Nobody was running make docs on their local machines (and verifying the output). There are qdoc errors that were put in by developers last December. Having the documentation modularized will at some point (hopefully soon) allow us to put documentation generation in the CI system. This would allow us to catch patches causing qdoc errors. 2. It was/is completely unclear how the system works, there hasn't been any QML documentation at http://doc-snapshot.qt-project.org/5.0/ for multiple weeks now (I believe 4, maybe more). Also, you seem to use the Module terminology to refer to library (QtCore, QtGui, ...) within qtbase. But some other people may refer to Module for the repositoies (qtbase, qtdeclarative, qtscript, ...). This is a bit confusing, please clarify. The term module in documentation equals library. There is no concept of repositories for the documentation. I went for what we use in qdoc (\module and \qmlmodule), sorry if that was unclear. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
There are 2 main problems with the current system: 1. Nobody was running make docs on their local machines (and verifying the output). There are qdoc errors that were put in by developers last December. Having the documentation modularized will at some point (hopefully soon) allow us to put documentation generation in the CI system. This would allow us to catch patches causing qdoc errors. 2. It was/is completely unclear how the system works, there hasn't been any QML documentation at http://doc-snapshot.qt-project.org/5.0/ for multiple weeks now (I believe 4, maybe more). But none of those problem will be fixed by modularizing the docs by libraries. Or am i missing something? (putting make docs in the CI is a good idea) The CI system the documentation will be built per repository, that is true, but there might be users who only want to build a specific set of libraries with documentation and the extra step of granularity will not make a difference (in my opinion), since the only difference would be a few extra qdocconf files and make targets. I also think that adding the documentation build closer to the source build (we could add the make corelib-docs target to corelib.pro) will make the whole system more transparent and (psychologically) easier to use. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Hi, We had cross-module links in both directions. We achieved this by running qdoc twice per module. Once to get the .index (used for resolving links) and again to build with the other modules' .index files. The only way to avoid doing things twice would be to have more intermediate steps in the doc building process (ie. generate indexes, etc for everything then bring those together into a final product and resolve all the links then). I have been thinking about this problem for some time, and while it is technically possible from a qdoc side to implement the whole system like this: I don't see the CI system handling anything like this, what we could do is have a previous run of all the index files somewhere for the CI system to find, but that would theoretically open up the possibilty that I remove a documentation \class from QtCore, but it will still be found in the index. The missing file will only show up when you run qhelpgenerator to generate the QCH files. And I haven't even talked about the qhelpgenerator/QCH process yet, because that thing is still in qttools and can therefore not be run in the CI for qtbase. - For cross-linking we need to do a few things (None of this is implemented yet): 1. We need to add a depends qdocconf variable, where you list the modules you depend on. Why?! We already have our dependencies stated in the sync.profile and module .pro files. Duplicating this information just causes a maintenance burden. Allowing explicit dependencies on docs (where there is no dependency between modules) may make sense but dependencies derived from the build should be extracted from the build. Adding this information extra in the qdocconf file will not be that harmful I think because we don't change the dependency tree that often anymore. But I would be grateful if you would make a plan on how to turn qdoc into a mini-qmake so that qdoc can parse the .pro/sync.profile, so that we don't need the depends. Because that would probably also mean that you have to run qdoc [module.pro] [module.qdocconf], or do you see that differently? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Missing QML Doc
Hi, tl;dr: Things have to be done, but they have not been done yet. It is mainly because qtdoc/doc/config/modules/qtdeclarative.qdocconf has not been split into a qtqml.qdocconf and qtquick.qdocconf. There is also some magic that has to be applied to qtdoc/doc/config/qt-project.qdocconf and qtdoc/doc/doc.pri Casper From: development-bounces+casper.vandonderen=nokia@qt-project.org [development-bounces+casper.vandonderen=nokia@qt-project.org] on behalf of ext Johan Thelin [e8jo...@gmail.com] Sent: Tuesday, March 27, 2012 10:47 AM To: Senyk Thomas (Nokia-DXM/Munich) Cc: development@qt-project.org Subject: Re: [Development] Missing QML Doc The same goes for qquickitem.html, present at http://doc.qt.nokia.com/qt5/qquickitem.html, but not at http://doc-snapshot.qt-project.org/5.0/quickitem.html . Best regards, Johan Thelin Recommended on-line reading: http://www.thelins.se | http://www.qtcentre.org Recommended off-line reading: The Foundations of Qt Development (ISBN: 1-59059-831-8) On Tue, Mar 27, 2012 at 10:43, Thomas Senyk thomas.se...@nokia.com wrote: Hi, does anyone know why: http://doc-snapshot.qt-project.org/5.0/qtquick2-qdeclarativeelements.html is missing (that's the link when you click on QML Elements) by the way: http://doc.qt.nokia.com/qt5/qtquick2-qdeclarativeelements.html exists. Greets Thomas ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] Qt Namespace enums defined in QTextDocument
Hi, The Qt::HitTestAccuracy and Qt::WhiteSpaceMode enum are defined in QTextDocument (which is in QtGUI), but they are documented in the Qt Namespace, which is in QtCore. This obviously does not work if we want to modularize the documentation on a library level. I have no idea how to solve this in an easy way, maybe we could do multiple runs on QtCore documentation (QtCore - QtGUI - QtCore), but that is not what I would like to do. Any ideas? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] qdoc3 will be removed from qtdoc (and creating packages for Alpha)
Hi all, I just put the patch in that removes qdoc3 from qtdoc. From then onwards there will only be qdoc in qtbase. It is in Gerrit as http://codereview.qt-project.org/#change,19829 That is one of the changes I think we need for the alpha (to not ship both qdoc3 and qdoc) Another thing we need is a correct documentation footer. I put those in Gerrit as 19825 and 19826. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Demos, examples, docs etc for Alpha release
Hi, Please read http://qt-project.org/wiki/Spelling_Module_Names_in_Qt_Documentation. That should contain module names for most modules and gives hints on what to use (I am aware that these guidelines are not followed everywhere) So if you have the source and see incorrect use of module names you are free to update the documentation and add me as a reviewer. Casper From: development-bounces+casper.vandonderen=nokia@qt-project.org [development-bounces+casper.vandonderen=nokia@qt-project.org] on behalf of Gil Quim (Nokia-DXM/SiliconValley) Sent: Tuesday, March 13, 2012 10:25 PM To: Knoll Lars (Nokia-MP/Oslo); Storm-Olsen Marius (Nokia-MP/Austin) Cc: development@qt-project.org Subject: Re: [Development] Demos, examples, docs etc for Alpha release Ok, here we go: http://qt-project.org/wiki/Qt-Essentials-Modules http://qt-project.org/wiki/Qt-Add-ons-Modules There are many inconsistencies listed at the Notes section of each page (and pasted below for convenience). Please help ironing these details. Unless it's a topic for discussion you can edit the wiki directly or reply to me personally (no need to flood the list with tiny details). Thanks! Essentials: * What is the right way to spell these modules? Qt Widget or QtWidget? Qt WebKit or QtWebkit… ? * Is “Qt Quick 2” the right name or “Qt Declarative” or…? * Is it “Qt JS Backend”, “V8 JavaScript engine” or…? * “Qt WebKit” is already listed as Add-on. Is it Essential or are we talking about the WebKit1 vs WebKit 2 difference here? * Is “Qt Test” = “qttestlib”? * Is “Qt System Info” = “qtsystems”? * Is Qt 3D an Essential or Add-on? * It seems Qt D-Bus, Qt Sensors are Add-ons? * Are Qt Service Framework, Qt Publish and Subscribe still in Essentials? Not in Alpha release? Add-ons: * Should these be added? qlarl, qtconnectivity, qtdoc, qtdocgallery, qtimageformats, Phonon (or Qt Phonon?), qtpim, qtplatformsupport, qtqa, qtrepotools, qttranslations, qtwebkit-examples-and-demos * Is it “ActiveQt”, qtactiveqt or…? * Is it “Qt JSON DB”, “Qt JsonDB” or…? * Is “qttools” = “Qt Script Tools” or “Qt UI Tools” or…? * Is “Qt WebKit” in Add-ons or Essentials or…? Plus these that were listed in the old page (feel free deleting them if they are not relevant anymore, or adding the comments to the cell of the appropriate component): * Phonon will be maintained upstream by KDE. * Open: Add Qt Quick components modules * Open: whether Qt 5.0 will include the Qt Document Gallery add-on module. * Open: whether Qt 5.0 will include the Qt Local connectivity add-on * Open: whether Qt 5.0 will include the Qt Messaging add-on -- Quim From: Knoll Lars (Nokia-MP/Oslo) Sent: Tuesday, March 13, 2012 12:56 PM To: Gil Quim (Nokia-DXM/SiliconValley); Storm-Olsen Marius (Nokia-MP/Austin) Cc: development@qt-project.org Subject: Re: [Development] Demos, examples, docs etc for Alpha release Hi Quim, sounds good, please go ahead. Cheers, Lars On 3/13/12 8:05 PM, ext quim@nokia.com quim@nokia.com wrote: (Sorry for top-posting from this web client) Thank you for the list of modules. Can I do the following changes to the wiki? 1. Move the list of modules at http://qt-project.org/wiki/Qt_5.0#66036ddf6d03c9ce1fc742741417f128 to two new pages: - Qt Essential Modules - Qt Add-on Modules Reasoning: the are not roadmap anymore and they are not even 5 exclusive. They are simply Qt modules in trunk. This way it's easier to link to them from other pages (e.g. Alpha release notes) without having to drag the whole Qt 5 Roadmap content. 2. Mark somehow (e.g. different background color) the modules available in the alpha release. Reasoning: to have a clear idea of the status of those modules. 3. Try to improve the names and descriptions of each module. Reasoning: now it's confusing. For instance, is qtjsbackend = V8 JavaScript engine? 4. Link each module to whatever landing page there is available somewhere in the wiki, if available. Reasoning: now only the insiders can bridge that list with whatever info is somewhere else. -- Quim From: Storm-Olsen Marius (Nokia-MP/Austin) Sent: Monday, March 12, 2012 9:05 PM To: Gil Quim (Nokia-DXM/SiliconValley) Cc: development@qt-project.org; Hausmann Simon (Nokia-MP/Oslo) Subject: Re: [Development] Demos, examples, docs etc for Alpha release On 12/03/2012 18:10, ext Quim Gil wrote: Also, a basic question: where can someone find the actual list of Essential and Add-on modules that will be included in the Alpha? A Work-in-progress list is fine, now the only reference I have is a slide from last October-November. The current release script generates a package (890MB tar = 251MB tar.gz), correlated with the categorization of modules at http://qt-project.org/wiki/Qt_5.0 and corrected with some recent discussions between Henry, Lars and Thiago, this list of modules: Qt Essentials: qt3d
Re: [Development] QDoc can't ignore Q_PROPERTY
So let's step back for a bit: I get not wanting to be forced into writing redundant 'emitted when this property has changed' documentation but excluding documentation that has been written for a signal seems a bit excessive, wouldn't it be enough to just omit the warning for an undocumented signal if it's a notify signal? That would work but the code to do that would be more complicated (can't just suppress warnings, must do document as property or document as signal depending on if the signal docs are found). Since I don't actually know the qdoc code, I went for a simple fix. If the above design pattern (co-opting a signal for NOTIFY) is common and suppressing the documentation for those signals will be a problem then I guess the more complicated fix will need to be done. The solution given above would mean that it will become optional to document NOTIFY signals. But is that not completely different from the original problem? To me it seems like the original problem was that method documentation would not show up when a property had the same name. Or did I misunderstand that? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] QDoc can't ignore Q_PROPERTY
Just to make sure everybody understands: With this change applied all NOTIFY properties that are currently documented will not be documented anymore. If there are no objections before coming Tuesday (13 March) 09:00 Oslo time I will put this patch in. Casper From: Ramsay Lincoln (Nokia-MP/Brisbane) Sent: Friday, March 09, 2012 12:37 AM To: Vandonderen Casper (Nokia-MP/Oslo) Cc: ext Girish Ramakrishnan; development@qt-project.org Subject: Re: [Development] QDoc can't ignore Q_PROPERTY On 03/08/2012 07:38 PM, Vandonderen Casper (Nokia-MP/Oslo) wrote: It might be that this was indeed an oversight. Can you create a bug report and assign it to me (I am not promising I have time to fix it now, or you can fix qdoc yourself and add me as reviewer ;-) ) Ok... The fix is (as far as I can tell) a single line of code. With that in place, NOTIFY signals are handled the same as getters and setters for properties. Perhaps most significantly, documentation for the signal is silently ignored by qdoc. While trying to find that line, I found two other bits of code dealing with getters and setters but not notifiers. I've updated them too but I don't actually know what they do. http://codereview.qt-project.org/#change,19374 -- Lincoln Ramsay - Senior Software Engineer Qt Development Frameworks, Nokia - http://qt.nokia.com/ ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] QDoc can't ignore Q_PROPERTY
It might be that this was indeed an oversight. Can you create a bug report and assign it to me (I am not promising I have time to fix it now, or you can fix qdoc yourself and add me as reviewer ;-) ) Casper On 3/8/12 3:56 AM, ext Girish Ramakrishnan gir...@forwardbias.in wrote: Hi, On Wed, Mar 7, 2012 at 5:48 PM, Lincoln Ramsay lincoln.ram...@nokia.com wrote: On 03/03/2012 02:25 AM, ext Thiago Macieira wrote: On sexta-feira, 2 de março de 2012 18.01.15, Denis Shienkov wrote: The fact is that if the names of class methods and the same properties names - then QDoc ignores the description for the methods. That's intentional. You document the property. The getter and setter methods do not need to be documented. I like this, but I don't like that you must explicitly document the NOTIFY signal for a property. Is there a particular reason that NOTIFY signals aren't handled the same as getters and setters? I think this is just an oversight. qdoc wasn't fixed after NOTIFY support was fully added. Girish ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] Moving qdoc to qtbase (and renaming from qdoc3 to qdoc)
Hi,
We are currently integrating a patch that moves qdoc3 to qtbase and renames it
to just qdoc. (http://codereview.qt-project.org/#change,18850)
This allows qdoc to be bootstrapped, so that you always have qdoc available and
that we can properly modularize the documentation.
Why do we do this:
- The Qt5 documentation is not modularized properly. We need qdoc in qtbase to
modularize. Since we don't want to compile qtbase, qtjsbackend, qtdeclarative
and qtdoc before you can run qdoc on QtCore.
- Last week qdoc lost forward compatibility with the \li change, it is not
possible anymore to run an older qdoc3 on the current Qt5 documentation any
more, a name change makes this difference clear.
- We have wanted to rename qdoc3 to qdoc for some time already.
What do we want to do next (don't expect this to be done by next week):
- Refactor the documentation to make it possible to run qdoc on just single
modules.
- Install .index files to some default installation location to make it
possible to run qdoc on individual modules and use the index file from other
modules automatically. This basically means that qdoc is run on QtCore, the
index file is installed somewhere, you then run qdoc on QtSql and it uses the
index file from QtCore automatically. I hope this addresses some of the often
requested functionality to run qdoc on a single folder.
- Move the documentation content around a bit. So that in qtbase the
documentation from QtCore is not in doc/src/corelib anymore, but in
src/corelib/doc.
- Make some more stuff hardcoded in qdoc, for instance a default
sources.fileextensions, which you can override using a qdocconf file. This
would hopefully make it possible to run qdoc without any qdocconf file at all.
If you run qdoc3 in your own projects you can use lessThan(QT_MAJOR_VERSION, 5)
{ } in your .pro/pri files to point to either qdoc3 or qdoc, this should allow
you to run both a Qt4 qdoc3 and a Qt5 qdoc. Where you will get warnings in the
qt5 qdoc because of the changes regarding \o, \li and \bold.
Casper
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] QtSerialPort need to check the documentation.
A complete Qt 5 qt.index file can be found at http://doc.qt.nokia.com/5.0-snapshot/qt.index It's an XML file, so your browser will open is as such, but it is 15M, so use something like CURL/wget Casper On 3/4/12 8:19 AM, ext Denis Shienkov scap...@yandex.ru wrote: Hi Debao. Thank you. Best regards, Denis 04.03.2012, 01:31, 1+1=2 dbzhang...@gmail.com: Hi Denis, you need to specify the qt.index file in your .qdocconf file. Such as indexes = $QTDIR/doc/html/qt.index More infofmation can be found here: http://doc.qt.nokia.com/qdoc/25-qdoc-configuration-derivedprojects.html Debao On Sat, Mar 3, 2012 at 10:59 AM, Denis Shienkov scap...@yandex.ru wrote: Hi all. I prepared the first to review QtSerialPort addon, which relates to the configuration documentation, and spelling in English. The project itself is here: $ git clone ssh://codereview.qt-project.org:29418/playground/qtserialport.git The review itself is here: http://codereview.qt-project.org/#change,18687 The structure of the documentation is not complete and not yet stabilized. I still just need to prepare a sample form and pattern of this documentation. I am also interested in the question: How to correct make qdocconf, that a QDoc correctly picks up the description of a virtual (or overloaded) methods of Qt? For example, the SerialPort class inherits from QIODevice. I'm doing for the SerialPort re-implement some virtual methods from QIODevice. And I need to make, that these methods from QIODevice (as well as himself QIODevice, it signals, etc.), linked to the documentation for the QtSerialPort. Help me please someone if you have free time in this matter. Best regards, Denis ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/9/12 10:44 PM, ext BRM bm_witn...@yahoo.com wrote: From: casper.vandonde...@nokia.com casper.vandonde...@nokia.com Just to add what I think to Marius' comments: 1. Doxygen would need some extra features, the major one being QML, but also being able to use index files to easily link for instance the Creator docs to the Qt docs. Why would Doxygen need QML itself? Or do you mean it would need to be able to process the QML/JavaScript files to get additional documentation? I mean that Doxygen needs to support parsing .qml files and .cpp files containing QML files (and that it should generate the same look of content for both of them). 2. Even if we would use Doxygen we would still need a fork before a release, I do not think we can line up releases of Doxygen with releases of Qt. And having a Doxygen version number like 1.7.6.2-qt-SHA1 also doesn't look too great. I can understand bundling a version of Doxygen with Qt in the release - like many projects do for their dependencies in case those things are not on the platform people are building on. E.g. Subversion bundles libneon. However, I see no issue with saying that Doxygen version x.y.z is required to support documentation. So why would we need to _fork_ it as opposed to simply bundling a version that is known to work? Doxygen does not support everything we need. Maybe at some point we (the Qt project) will not require any new features from the documentation tool, then we can obviously just ship a Doxygen version that is known to work. What I mean is that in the beginning we'll probably have a situation similar to Gerrit, where we have a version deployed with the Qt project that is mainline with some extra patches applied (which is a fork in my book, or at least temporarily, until the patches are integrated in mainline). That would not occur when Doxygen releases are lined up with Qt (or when we get lucky and Doxygen releases a version before a Qt release which has all our patches applied). Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/10/12 8:07 AM, ext Andre Somers an...@familiesomers.nl wrote: Op 9-2-2012 19:13, marius.storm-ol...@nokia.com schreef: On 09/02/2012 10:33, ext Manuel Nickschas wrote: On Thursday 09 February 2012 15:36:09 ext Olivier Goffart wrote: I am working on QDoc part-time and we have been discussing some changes that we would like to implement to make qdoc more future proof. I have created a short list of the things we would like to do: http://developer.qt.nokia.com/wiki/Category:Tools::QDoc It comes down to: Implement a new C++ parser, make qdoc more modular and be able to handle the Qt modules better with qdoc. I am wondering if anybody has any ideas about what he/she would like qdoc to do, or how qdoc should evolve? Have you thought about using doxygen or any similar tool? Or at least make QDoc be able to parse doxygen-style comments (which also means it should not ignore headers, as documenting public API in a header file is much more common at least outside Qt than doing that in the implementation file...) Qt puts the documentation in the sources since it's closer to the actual code, and thus more likely to be maintained at the same time as the code is changed. If the documentation is in another location, it's far more likely to be forgotten when updates/changes to behavior is done in the source code. That only goes for code that is actually *in* the cpp files. It does not hold for enums, flags, inline functions and typedefs, nor does it hold for the many cases where the code is actually in a private class and the implementation contains little more than a d-doSomething(). I'm not saying that putting all documentation in the header file is better, but it would IMHO be better if we were able to put the documentation at a place were we do not need to repeat ourselves. As you say: that makes it less likely to be properly updated. That results in being able to parse both the headers *and* the sources. For the rest, you make excellent points. If doxygen really is that closed, and it is currently not up to par with what Qt needs, then we need to stick with qdoc. However, the general idea to use what is out there instead of trying to maintain every part of the toolchain ourselves does appeal to me in general. André Just to reply to the comments in header/enum comments in one go: Let's first say that I think it would be great to also be able to write documentation directly in the header. It can lead to a mess though. We would need some clearly defined boundaries about where to put documentation. We already have classes where some of the function documentation is a the top of the cpp file with \fn (even though they are not defined in the header) and some of the documentation is next to the functions. We would also need to reach agreement about how to document enums in headers, does not having documentation mean that you just want to print the enum value, and should you explicitly use \omitvalue to not print anything? I do not know enough about how compilers work (I read some stuff about how Clang works), but does adding the documentation to the headers not make compilation slower? Since the file that needs to be loaded by the preprocessor is bigger? And if that is the case: are we willing as a group of users that documentation causes builds to be slower? (I don't think we do) Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] RFC: The Future of QDoc
Hello, I am working on QDoc part-time and we have been discussing some changes that we would like to implement to make qdoc more future proof. I have created a short list of the things we would like to do: http://developer.qt.nokia.com/wiki/Category:Tools::QDoc It comes down to: Implement a new C++ parser, make qdoc more modular and be able to handle the Qt modules better with qdoc. I am wondering if anybody has any ideas about what he/she would like qdoc to do, or how qdoc should evolve? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/9/12 3:15 PM, ext Keno Fischer ke...@stanford.edu wrote: Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? I think that QDoc will indeed use the parser from Creator (whatever that will be, the last answer from Andre Poenitz was to use a hybrid), unless someone comes up with other great ideas. The problem stays that QDoc is not fully modularized (QDoc will depend on Creator/an independent module containing the parser). But maybe that is something we cannot circumvent (unless we let QtBase depend on Clang and have our own parser, but that will not work on every platform I assume). Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
Hi, I nice ability QDoc would have is to support other output formats like XML or JSON, the old QDoc had this feature but it was deprecated and not documented at all. The PySide documentation is generated using the XML output of qdoc3, but the current version of qdoc3 doesn't support XML output anymore. Oops. Casper, Martin any details about this, and why XML output was dropped? Hugo, any reason why PySide cannot use the normal output? Integration with other help tools? XML output was dropped because it wasn't maintained and was never made public, it always was a private experimental thing from qdoc3. We couldn't use the normal output because we need to modify the Qt documentation without touch the Qt sources, so the qdoc3 outputs XML files generated from Qt sources, we apply some XSLT's to change small things, then we transform those XML's into rst files and send them to sphinx to create the docs formatted in a python friendly way. Have you looked at the DITA XML output we generate now? It is pretty stable now, we tried to use it for the 4.8 DevNet release, but the output was not fully up to spec at that point. It is now. You can find more information about DITA XML at http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html The version of DITA Open Toolkit we are using to apply XSLTs can be found at https://projects.developer.nokia.com/doxygen_dita/files Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 09/02/2012 10:33, ext Manuel Nickschas wrote: On Thursday 09 February 2012 15:36:09 ext Olivier Goffart wrote: I am working on QDoc part-time and we have been discussing some changes that we would like to implement to make qdoc more future proof. I have created a short list of the things we would like to do: http://developer.qt.nokia.com/wiki/Category:Tools::QDoc It comes down to: Implement a new C++ parser, make qdoc more modular and be able to handle the Qt modules better with qdoc. I am wondering if anybody has any ideas about what he/she would like qdoc to do, or how qdoc should evolve? Have you thought about using doxygen or any similar tool? Or at least make QDoc be able to parse doxygen-style comments (which also means it should not ignore headers, as documenting public API in a header file is much more common at least outside Qt than doing that in the implementation file...) Qt puts the documentation in the sources since it's closer to the actual code, and thus more likely to be maintained at the same time as the code is changed. If the documentation is in another location, it's far more likely to be forgotten when updates/changes to behavior is done in the source code. I'd be happy to see Qt use or at least support more standard solutions over homegrown ones. Since that failed for localization, maybe we can at least get it for documentation :) Just to add what I think to Marius' comments: 1. Doxygen would need some extra features, the major one being QML, but also being able to use index files to easily link for instance the Creator docs to the Qt docs. 2. Even if we would use Doxygen we would still need a fork before a release, I do not think we can line up releases of Doxygen with releases of Qt. And having a Doxygen version number like 1.7.6.2-qt-SHA1 also doesn't look too great. I would personally not mind using Doxygen, but I do agree with the points about Dimitri only changing the code and the quality of Doxygen output (which you can of course change) Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
