Proyectos derivados compatibles

Algunas variables de configuración le permiten utilizar QDoc para dar soporte a proyectos basados en Qt. Permiten que su 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 las clases, sin ningún comando de enlace explícito.

descripción

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

Véase también proyecto.

índices

La variable indexes define un conjunto de rutas a los archivos de índices que se deben cargar.

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

La variable indexes proporciona una alternativa a depends para definir las dependencias del proyecto. Como se proporcionan rutas directas, no se requieren opciones de línea de comandos -indexdir al invocar QDoc.

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

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

nombredelproducto

Utilice la variable productname si el nombre del producto que se está documentando es diferente del nombre de la documentación. project Esto es especialmente útil para conjuntos de documentación más grandes 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 comando \since comando

Por ejemplo, Qt define Qt como productname, mientras que cada módulo individual define su propio nombre project. Esto permite a los autores utilizar la notación abreviada para el comando \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 formar un nombre de archivo para el 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, éstos se sustituyen por guiones ('-') en el nombre del fichero índice generado.

Véase también dependencias, índices y descripción.

raíz del proyecto

La variable projectroot establece el directorio raíz del proyecto para el cálculo de la ruta relativa en los registros de advertencia.

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 establece ninguna de las dos, se utilizan rutas absolutas

Cuando se establece una raíz de proyecto, QDoc convierte las rutas absolutas de los archivos en rutas relativas en los archivos de registro de advertencias. De este modo, los registros pueden transferirse a distintos entornos de compilación.

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

Para el uso autónomo de QDoc, la configuración de projectroot permite la portabilidad de los registros de advertencia:

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 usamos el índice por sí mismo, QDoc usará esto como la URL base cuando construya enlaces a clases, funciones y otras cosas listadas en el índice.

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

...

Esto asegura que siempre que QDoc genere referencias a entidades en el módulo Qt Core, la URL base sea https://doc.qt.io/qt/.

Véase también depends, indexes y url.examples.

url.ejemplos

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 ejemplos. La variable url.examples se refiere al directorio raíz de los ejemplos relacionados con este proyecto; puede ser un enlace a un repositorio en línea (empezando por http:// o https://), o al sistema de archivos local (file://).

Si url.examples no está definida, QDoc mostrará una lista de archivos e imágenes de ejemplo.

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, puede utilizarse \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 arriba y asumiendo 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 Esta variable se introdujo en la versión 5.13 de QDoc.

Ver también url, examplesinstallpath, y \example.

url.fuentes

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

Habilita los enlaces a las fuentes estableciendo url.sources.enabled en true. Cuando está habilitado, 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, defina el directorio raíz de las fuentes 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 especifica 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 de enlace visible para el usuario para los enlaces fuente. Por defecto, el texto del enlace es una cadena vacía; utilice el selector CSS a.srclink para dar estilo a los enlaces en la salida HTML.

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ífica 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, es deseable proporcionar un "tooltip" para las imágenes cuando se muestran en navegadores gráficos. QDoc ofrece una forma de hacerlo, en la que el texto alternativo dado como cadena opcional al comando \image se utiliza también como atributo de título de la imagen. Habilite este comportamiento estableciendo la variable this con usealttextastitle = true en el archivo de configuración de QDoc.

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

Cómo soportar proyectos derivados

Esta característica hace uso de los índices exhaustivos generados por QDoc cuando crea la documentación de referencia de Qt.

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

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

...

El nombre de la variable de proyecto se utiliza para formar un nombre de archivo para el archivo de índice; en este caso se crea el archivo qtgui.index. La url se almacena en el archivo de índice. Después, QDoc usará esto como el URL base cuando construya enlaces a clases, funciones, y otras cosas listadas en el índice.

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