Details
-
User Story
-
Resolution: Unresolved
-
P2: Important
-
None
-
None
-
DaVinci 115, DaVinci 116, DaVinci 117
Description
The \include and \snippet commands search directories listed in the exampledirs and (presumably) sourcedirs variables of the modules' qdocconf file. And qdoc also respects keywords and link targets from any module that is listed in the depends variable. But qdoc does not search for quotable files in the modules listed as depends (ie. in the sourcedirs from those modules' qdocconf files). So it is not possible to quote a piece of code from an example that lives in another repository.
This is problematic, for at least two reasons: the qtdoc repository is today the primary location for examples that are using Qt APIs from multiple modules, esp if those modules are dependent on each other. I.e. we cannot have an example in Qt GUI that uses Qt Quick; such an example has to live in qtdoc. But we would surely like to show reference QML code in the Qt GUI API reference documentation. The qdocconf file for Qt Gui does list Qt QML as a depends, but the exampledirs from Qt Gui's qdocconf file are not added to the current configuration.
And without being able to quote from different submodules or repositories, the whatsnew file has to be updated in a separate change request. New APIs cannot be added to the whatsnew file in the same change as the API that is added. This is error prone, and results in us forgetting to mention new additions. The work to cross check that all new APIs (as tagged with \since) are also mentioned in the whatsnew file is laborious. If we could make the whatsnew69.qdoc file just quote the whatsnew files that are maintained in each submodule, then this problem would go away.
FWIW, the directories currently searched when trying to quote a snippets file from e.g. whatsnew69.qdoc are
/Users/vohi/qt/dev-build/qtbase/doc/global/snippets /Users/vohi/qt/dev/qtdoc/doc/edu/images /Users/vohi/qt/dev/qtdoc/doc/images /Users/vohi/qt/dev/qtdoc/doc/snippets /Users/vohi/qt/dev/qtdoc/doc/src /Users/vohi/qt/dev/qtdoc/doc/src/images /Users/vohi/qt/dev/qtdoc/examples /Users/vohi/qt/dev/qtdoc/examples/demos/FX_Material_Showroom/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/calqlatr/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/car-configurator/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/clocks/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/coffee/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/colorpaletteclient/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/dice/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/documentviewer/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/hangman/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/lightningviewer/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/maroon/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/mediaplayer/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/osmbuildings/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/photosurface/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/robotarm/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/rssnews/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/samegame/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/stocqt/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/thermostat/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/todolist/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/windowembedding/doc/images /Users/vohi/qt/dev/qtdoc/examples/demos/xr_physicsbase_teleportation/doc/images
The first entry is interesting, in that it comes from the global config.qdocconf.
Attachments
Gerrit Reviews
For Gerrit Dashboard: QTBUG-134609 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
634901,2 | Add CMake logic to fetch documentation sources from external locations | dev | qt/qtdoc | Status: NEW | 0 | 0 |
634904,1 | Doc: QtCore: Add .qdocinc file for `What's New` documentation | dev | qt/qtbase | Status: NEW | 0 | 0 |