En esta página

Proyectos derivados compatibles

Algunas variables de configuración te permiten utilizar QDoc para dar soporte a proyectos basados en Qt. Estas permiten que tu proyecto contenga enlaces a la documentación en línea de Qt, lo que significa que QDoc podrá crear enlaces a la documentación de referencia de clases sin necesidad de ningún comando de enlace explícito.

descripción

La variable «description» contiene una breve descripción del proyecto asociado.

Véase también «project».

índices

La variable ` indexes ` define un conjunto de rutas a los archivos de índice que se van a cargar.

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

La variable ` indexes ` ofrece una alternativa a `depends` para definir las dependencias del proyecto. Al proporcionarse rutas directas, no se requiere ninguna opción de la línea de comandos ` --indexdir ` al ejecutar QDoc.

Es posible definir dependencias utilizando cualquiera de las dos variables. La documentación de Qt solo utiliza la variable « depends ».

Véase también «depends», «project » y «url».

preliminar

Utiliza la variable « preliminary » para personalizar el descriptor de estado asignado a los elementos mediante el \preliminary comando.

De forma predeterminada, QDoc marca estos elementos con el descriptor « Preliminary » en la referencia de la API y genera un mensaje

Este <tipo de elemento> está en fase de desarrollo y está sujeto a cambios.

En el cuerpo de la documentación del elemento, QDoc sustituye <tipo de elemento> en el mensaje anterior por el tipo (por ejemplo, «módulo», «función» o «clase»).

Para utilizar un descriptor de estado personalizado, define una variable preliminary:

preliminary = "Technology preview"

Para utilizar un mensaje de estado personalizado, define también una subvariable « preliminary.description »:

preliminary = "Technology preview"
preliminary.description = "This \1 is in technology preview and is subject to change."

Si aparece un marcador de posición « \1 » en la descripción, QDoc lo sustituye por el tipo de elemento.

La variable preliminary se introdujo en QDoc en Qt 6.12.

productname

Utiliza la variable productname si el nombre del producto que se está documentando es diferente del nombre de la documentación project Esto resulta especialmente útil en conjuntos de documentación de gran tamaño que constan de varios proyectos y/o módulos de documentación, ya que permite a QDoc generar el nombre del producto en lugar del nombre del proyecto en determinados contextos, como el \since comando.

Por ejemplo, Qt define Qt como el productname, mientras que cada módulo individual define su propio nombre project. Esto permite a los autores utilizar la notación abreviada para el \since comando.

Esta variable de configuración se introdujo en QDoc con Qt 6.9.

Véase también \since.

proyecto

La variable « project » proporciona un nombre para el proyecto asociado al archivo « .qdocconf ». Se trata de una variable obligatoria que todos los proyectos deben establecer.

El nombre del proyecto se utiliza para generar el nombre del archivo de índice del proyecto asociado.

project = QtCreator

Esto hará que se cree un archivo de índice llamado qtcreator.index.

Si el nombre del proyecto contiene espacios en blanco o caracteres especiales, estos se sustituyen por guiones («-») en el nombre del fichero de índice generado.

Véanse también «depends», «indexes» y «description».

raíz del proyecto

La variable projectroot establece el directorio raíz del proyecto para el cálculo de rutas relativas en los registros de advertencias.

projectroot = /path/to/project/root

QDoc utiliza el siguiente orden de prioridad para determinar la raíz del proyecto:

  1. QDOC_PROJECT_ROOT variable de entorno
  2. projectroot variable de configuración
  3. Si no se ha establecido ninguna de las dos, se utilizan rutas absolutas

Cuando se establece una raíz del proyecto, QDoc convierte las rutas absolutas de los archivos en rutas relativas en los archivos de registro de advertencias. Esto permite que los registros sean compatibles con diferentes entornos de compilación.

El sistema de compilación de Qt establece automáticamente ` QDOC_PROJECT_ROOT`, por lo que normalmente no es necesario configurar ` projectroot ` manualmente.

Para el uso independiente de QDoc, establecer projectroot permite obtener registros de advertencias portables:

projectroot = /home/user/myproject
logwarnings = true

La variable projectroot se introdujo en QDoc 6.11. Véase también logwarnings.

url

La variable url contiene la URL base de la documentación asociada al proyecto actual.

La URL se almacena en el archivo de índice generado para el proyecto. Cuando utilizamos el índice por sí solo, QDoc utilizará esta URL como URL base a la hora de crear enlaces a clases, funciones y otros elementos que figuran en el índice.

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

Esto garantiza que, cada vez que QDoc genere referencias a entidades del módulo Qt Core, la URL base sea https://doc.qt.io/qt/.

Véanse también: depends, indexes y url.examples.

url.examples

La variable « url.examples » contiene la URL base de los ejemplos asociados al proyecto actual.

Si se define, se genera un enlace al directorio del proyecto de ejemplos al final de cada página de documentación de los ejemplos. La variable url.examples hace referencia al directorio raíz de los ejemplos relacionados con este proyecto; puede ser un enlace a un repositorio en línea (que comience por http:// o https://) o al sistema de archivos local (file://).

Si no se define url.examples, QDoc mostrará en su lugar una lista de los archivos e imágenes de los ejemplos.

Por ejemplo, dadas estas definiciones:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

Entonces, para el siguiente \example comando:

/*!
    \example threads/semaphores
    ...
*/

QDoc genera un enlace a https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.

Si la URL contiene más componentes (por ejemplo, una cadena de consulta) después de la ruta de ejemplo, se puede utilizar \1 como marcador de posición para la ruta:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

Dado el mismo comando \example que el anterior y suponiendo que $QT_VER se expande a 5.13, la URL generada es https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.

url.examples La variable se introdujo en la versión 5.13 de QDoc.

Véase también url, examplesinstallpath y \example.

url.sources

La variable « url.sources » contiene la URL base del código fuente de C++ asociado al proyecto actual. Se trata de una URL para consultar el código fuente del proyecto en un repositorio, por ejemplo, en github.com.

Para habilitar los enlaces a los archivos fuente, configura url.sources.enabled en true. Cuando está habilitada, QDoc genera un enlace a una declaración en la sinopsis (firma) de cada entidad C++ documentada, en su sección «Descripción detallada ».

Además, define el directorio raíz de los archivos fuente con url.sources.rootdir. El enlace generado se compone de la URL base (url.sources) y la ruta del archivo fuente, relativa a url.sources.rootdir.

Si la URL contiene más componentes después de la ruta (por ejemplo, una cadena de consulta que especifique una rama), \1 actúa como marcador de posición para la ruta. Del mismo modo, \2 actúa como marcador de posición para el número de línea.

url.sources.linktext Establece el texto del enlace visible para el usuario en los enlaces de origen. Por defecto, el texto del enlace es una cadena vacía; utiliza el selector CSS a.srclink para aplicar estilos a los enlaces en el código HTML resultante.

Por ejemplo, con la siguiente configuración en qtbase/src/gui/doc/qtgui.qdocconf:

url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
url.sources.rootdir = ../../..    # root of the `qtbase` repository
url.sources.linktext = "(source)"
url.sources.enabled = true

QDoc generará enlaces a code.qt.io para cada entidad C++ documentada, específicos de la rama definida con la variable de entorno QT_VER.

La variable url.sources se introdujo en QDoc con Qt 6.10.

usealttextastitle

En algunos casos, resulta conveniente proporcionar una «información sobre herramientas» para las imágenes cuando se visualizan en navegadores gráficos. QDoc ofrece una forma de hacerlo, en la que el texto alternativo, proporcionado como una cadena opcional al \image comando se utilice también como atributo «title» de la imagen. Para habilitar este comportamiento, configura esta variable con usealttextastitle = true en tu archivo de configuración de QDoc.

Esta variable de configuración se introdujo en QDoc con Qt 6.9.

Cómo dar soporte a proyectos derivados

Esta función utiliza los índices exhaustivos generados por QDoc al crear la documentación de referencia de Qt.

Por ejemplo, qtgui.qdocconf (el archivo de configuración de Qt GUI) contiene las siguientes definiciones de variables:

project     = QtGui
description = Qt GUI Reference Documentation
url         = https://doc.qt.io/qt/

...

El nombre de la variable «project» se utiliza para formar el nombre del archivo de índice; en este caso, se crea el archivo qtgui.index. La URL se almacena en el archivo de índice. Posteriormente, QDoc la utilizará como URL base a la hora de crear enlaces a clases, funciones y otros elementos que figuran en el índice.

Véase también «depends», «indexes», «project» y «url».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.