List of .tags files for doxygen for Qt5 and Qt6

Mesrine

@Mesrine I found the answer to my question
The tags are online like "https://doc.qt.io/qt-6/qtcore.tags"

Paul Colby

If it helps, here's how I handle it for my open source projects, using CMake:

# ~~Find Qt. This will set, among other things, QT_TAGFILES_PATH we'll use below.~~
# Edit: this is not true. QT_TAGFILES_PATH is non-standard.  See later replies below.
find_package(QT REQUIRED COMPONENTS Core ... NAMES Qt6 Qt5)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core ...)

...

# Include Qt doc tagfiles, if provided.
if (QT_TAGFILES_PATH)
  set(QT_DOCS_BASEURL "https://doc.qt.io/qt-${QT_VERSION_MAJOR}/")
  message(STATUS "Using Qt doc tagfiles ${QT_TAGFILES_PATH} (${QT_DOCS_BASEURL})")
  set(DOX_TAGFILES "\\
  \"${QT_TAGFILES_PATH}/qtcore/qtcore.tags=${QT_DOCS_BASEURL}\" \\
  \"${QT_TAGFILES_PATH}/qtbluetooth/qtbluetooth.tags=${QT_DOCS_BASEURL}\" \\")
  # Add more Qt modules here, if relevant.
endif()

...

configure_file(doxyfile.in public.doxy)

Then, in my doxyfile.in, I have:

TAGFILES = ${DOX_TAGFILES}

Works well for me :)

Cheers.

Mesrine

@Paul-Colby said in List of .tags files for doxygen for Qt5 and Qt6:

QT_TAGFILES_PATH

Thanks. But still, you have to download the tags locally.
So the variable QT_TAGFILES_PATH is the path where the tags are stored locally?

Also I can not find the tags for qtmqtt Any idea?

Paul Colby

Hi @Mesrine,

Thanks. But still, you have to download the tags locally.

Only in the same way that you have to download the Qt libraries locally.

For example, on Ubuntu, you can install the qtbase5-doc-dev package, or use the Qt Online Installer.

So the variable QT_TAGFILES_PATH is the path where the tags are stored locally?

Yes. For example, if you install qtbase5-doc-dev, the tags are /usr/share/qt5/doc/*/*.tags, so QT_TAGFILES_PATH is /usr/share/qt5/doc.

Likewise, if you install via the Qt Online Installer, the path is /the/path/you/chose/to/install/Qt/to/Doc/Qt-<version>/.

But you don't need to figure that out yourself - Qt's CMake module will set QT_TAGFILES_PATH for you via find_package(Qt...) (assuming you have the tag files installed).

Also I can not find the tags for qtmqtt Any idea?

Sorry, I haven't worked with the Qt MQTT module, so can't say. I would expect that installing the module will bring the tag files with it, but its not available for me to install myself, so I can test that hypothesis.

Cheers.

Mesrine

@Paul-Colby
Thanks again,

I normally download the tags from the web, so, I do not have to install Qt locally to have the tags to build the documentation.
Like:

file(DOWNLOAD "https://upload.cppreference.com/mwiki/images/f/f8/cppreference-doxygen-web.tag.xml"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/cppreference-doxygen-web.tag.xml")
	file(DOWNLOAD "https://doc.qt.io/qt-6/qtcore.tags"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtcore.tags")
	file(DOWNLOAD "https://doc.qt.io/qt-6/qtnetwork.tags"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtnetwork.tags")
	file(DOWNLOAD "https://doc.qt.io/qt-6/qtwebsockets.tags"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtwebsockets.tags")

...
set(DOXYGEN_TAGFILES
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtcore.tags=http://doc.qt.io/qt-6/"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtnetwork.tags=http://doc.qt.io/qt-6/"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/qtwebsockets.tags=http://doc.qt.io/qt-6/"
		"${CMAKE_CURRENT_BINARY_DIR}/doxtags/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
		)
doxygen_add_docs(
		doxygen_docs
		${PROJECT_SOURCE_DIR}/README.md
		${PROJECT_SOURCE_DIR}/include
		${DOC_SOURCE_DIRS}
		COMMENT "Generate man pages"
		)

The full cmake here.

redtide

@Paul-Colby:

But you don't need to figure that out yourself - Qt's CMake module will set QT_TAGFILES_PATH for you via find_package(Qt...) (assuming you have the tag files installed).

I would like to know why this doesn't work for me, searching in the web and in the CMake modules directories the only place that has the QT_TAGFILES_PATH string is this thread.
Here I have Archlinux with both qt5 and qt6 doc packages with tags installed.
Any idea?

Paul Colby

@redtide said in List of .tags files for doxygen for Qt5 and Qt6:

searching in the web and in the CMake modules directories the only place that has the QT_TAGFILES_PATH string is this thread.

My apologies! It turns out I made that variable up for my own projects (I completely forgot), and its not something that's built-in to find_package(Qt ...) (contrary to what I wrote above).

I have a custom "bootstrap" script that runs CMake to create build directories for every installed version of Qt (both OS packager installed ones, and Qt Online Installer ones; and also clang scan-build versions of each). Among other things, it detects the tag files and sets QT_TAGFILES_PATH for me, like:

if [[ -e "${qts[$qtVersion]}../../Docs/Qt-${qtVersion%-*}/qtcore/qtcore.tags" ]]; then
  qtTagsDir=$(realpath "${qts[$qtVersion]}../../Docs/Qt-${qtVersion%-*}")
elif [[ -e "${qts[$qtVersion]}../share/qt${qtVersion%%.*}/doc/qtcore/qtcore.tags" ]]; then
  qtTagsDir=$(realpath "${qts[$qtVersion]}../share/qt${qtVersion%%.*}/doc")
fi
cmake ... ${qtTagsDir:+-D "QT_TAGFILES_PATH=${qtTagsDir}"} ...

For example, for Ubuntu's default Qt5, this becomes:

cmake -D "QT_TAGFILES_PATH=/usr/share/qt5/doc" ...

But it occurs to me now that I could implement this detection as a CMake function that runs after find_package(QT ...), without any need for the Bash detection, so I'll do that for my own interest sometime in the next few days, and share what I come up with.

That said, I really like @Mesrine's approach above of having CMake download the tags files too :)

Cheers.

redtide

@Paul-Colby
No problem! Thank you for the suggestions and for the quick response!
I thought to do a little CMake module for that, I'll wait for your results then!

Paul Colby

Here's what I have so far (I'm sure it could be better):

# Attempt to detect the QT_INSTALL_DOCS path via qtpaths, or qmake.
if(NOT QT_INSTALL_DOCS)
  if(QT_VERSION VERSION_GREATER_EQUAL 6.2.0 AND TARGET Qt${QT_VERSION_MAJOR}::qtpaths)
    message(DEBUG "Fetching location of imported Qt${QT_VERSION_MAJOR}::qtpaths command")
    get_target_property(COMMAND Qt${QT_VERSION_MAJOR}::qtpaths LOCATION)
  elseif(TARGET Qt${QT_VERSION_MAJOR}::qmake)
    message(DEBUG "Fetching location of imported Qt${QT_VERSION_MAJOR}::qmake command")
    get_target_property(COMMAND Qt${QT_VERSION_MAJOR}::qmake LOCATION)
  else()
    message(STATUS "Neither Qt${QT_VERSION_MAJOR}::qtpaths nor Qt${QT_VERSION_MAJOR}::qmake available")
  endif()
  if (COMMAND)
    message(VERBOSE "Fetching QT_INSTALL_DOCS from ${COMMAND}")
    execute_process(
      COMMAND "${COMMAND}" -query QT_INSTALL_DOCS
      RESULT_VARIABLE COMMAND_RESULT
      OUTPUT_VARIABLE COMMAND_OUTPUT
      ERROR_VARIABLE COMMNAD_ERROR
      OUTPUT_STRIP_TRAILING_WHITESPACE
      ERROR_STRIP_TRAILING_WHITESPACE)
    message(DEBUG "${COMMAND} result: ${COMMAND_RESULT}")
    message(DEBUG "${COMMAND} output: ${COMMAND_OUTPUT}")
    message(DEBUG "${COMMAND} error: ${COMMAND_ERROR}")
    if(COMMAND_RESULT EQUAL 0)
      set(QT_INSTALL_DOCS "${COMMAND_OUTPUT}")
      message(STATUS "Found QT_INSTALL_DOCS: ${QT_INSTALL_DOCS}")
    else()
      message(STATUS "Failed to find QT_INSTALL_DOCS: ${COMMAND_OUTPUT} ${COMMAND_ERROR} [${COMMAND_RESULT}]")
    endif()
  endif()
endif()

# Include Qt doc tagfiles, if available.
if (QT_INSTALL_DOCS)
  set(QT_DOCS_BASEURL "https://doc.qt.io/qt-${QT_VERSION_MAJOR}/")
  message(STATUS "Using Qt doc tagfiles ${QT_INSTALL_DOCS} (${QT_DOCS_BASEURL})")
  set(DOX_TAGFILES "\\
  \"${QT_INSTALL_DOCS}/qtcore/qtcore.tags=${QT_DOCS_BASEURL}\" \\
  \"${QT_INSTALL_DOCS}/qtbluetooth/qtbluetooth.tags=${QT_DOCS_BASEURL}\" \\")
endif()

It uses qtpaths -query QT_INSTALL_DOCS for Qt 6.2+ since -query was only added to qpaths in Qt 6.2.0, otherwise uses qmake -query QT_INSTALL_DOCS, which does the same thing (and is still supported, but presumably being phased out in preference for qtpaths).

This works for Ubuntu (Canonical provided packages, Qt Online Installer versions, and aqtinstall versions), macOS (aqtinstall) and Windows (aqtinstall), for Qt versions 5.9.9 through to 6.7.0 Beta - ie all the platforms I have available for testing :)

I haven't structured it as a CMake module yet, but if I do sometime, I'd probably make it so you could do something like:

find_package(QtDocTag COMPONENTS Core Bluetooth ...)

And have it it set individual variables with the full paths to each component's tag file. But that's an exercise for another day :)

PS Qt's cmake modules do set some doc-related variables, but as far as I can tell, they are set to a default install target path (typically ./doc) which is (your/my) project's docs, not the path of the installed Qt version, which is overridden during installation by the various packaging systems (including Qt Online Installer), so not at all valid for the linked Qt installation.

Cheers.

redtide

@Paul-Colby excellent! Thank you very much!
Qt 5.15 and 6.2 here. I saved it as .cmake file and included in the main script,
using TAGFILES = @DOX_TAGFILES@ in my Doxyfile.in.
Very handy also to be used in a CI for the web documentation via Git branch.
Do we need to use some license for the feedback?

Paul Colby

@redtide said in List of .tags files for doxygen for Qt5 and Qt6:

@Paul-Colby excellent! Thank you very much!

You're very welcome :D

I've improved it a bit, and wrapped it up into a CMake module here: FindQtDocs.cmake. You can read some (very basic) documentation here, but the quick version:

# Find Qt
find_package(QT REQUIRED COMPONENTS Core Bluetooth NAMES Qt6 Qt5)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Bluetooth)

# Find Qt docs
include(FetchContent)
FetchContent_Declare(FindQtDocs GIT_REPOSITORY "https://github.com/pcolby/cmake-modules" GIT_TAG "v1")
FetchContent_MakeAvailable(FindQtDocs)
list(PREPEND CMAKE_MODULE_PATH "${findqtdocs_SOURCE_DIR}")
find_package(QtDocs COMPONENTS Core Bluetooth)

# Include Qt doc tagfiles, if available.
if (QtDocs_FOUND) # Or use `REQUIRED` above.
  set(QT_DOCS_BASEURL "https://doc.qt.io/qt-${QT_VERSION_MAJOR}/")
  message(STATUS "Using Qt doc tagfiles ${QT_INSTALL_DOCS} => ${QT_DOCS_BASEURL}")
  set(DOX_TAGFILES "\\
  \"${QtDocs_Core_TAGS}=${QT_DOCS_BASEURL}\" \\
  \"${QtDocs_Bluetooth_TAGS}=${QT_DOCS_BASEURL}\" \\")
endif()

Do we need to use some license for the feedback?

I've released the module under BSD-3-Clause (the same as CMake, itself). Contributions more than welcome :)

Cheers.

redtide

@Paul-Colby I've released the module under BSD-3-Clause (the same as CMake, itself). Contributions more than welcome :)

Great! I'll give you some feedback when I'll add it to a small kit of mine with the same license to be installed in Linux systems, as support for some applications I made.
Thank you again for this!