El archivo de configuración de QDoc

Antes de ejecutar QDoc, debe crear un archivo de configuración QDoc para indicar a QDoc dónde encontrar los archivos fuente que contienen los comentarios QDoc. La ruta del archivo de configuración se pasa a QDoc en la línea de comandos:

/current/dir$ ../../bin/qdoc ./config.qdocconf

Descripción general

El archivo de configuración es una lista de entradas de la forma "variable = valor". Mediante las variables de configuración, puede definir dónde debe encontrar QDoc los distintos archivos fuente, imágenes y ejemplos, dónde colocar la documentación generada, etc. El archivo de configuración también puede contener directivas como include. Para ver un ejemplo, consulte minimum.qdocconf.

También puedes usar variables de configuración para que QDoc soporte proyectos derivados, es decir, QDoc puede generar enlaces en la documentación de tu proyecto a elementos de la documentación online de Qt. Consulte la sección Soporte de proyectos derivados.

Un nombre válido de variable de configuración puede incluir letras mayúsculas y minúsculas, números y un guión bajo, '_'.

El valor de una variable de configuración puede establecerse utilizando '=' o '+='. La diferencia es que '=' anula el valor anterior, mientras que '+=' añade un nuevo valor al actual.

Los valores de algunas variables de configuración se interpretan como una lista de cadenas, por ejemplo: sourcedirsmientras que otras se tratan como una única cadena. Las comillas dobles alrededor de una cadena de valores son opcionales, pero incluirlas permite utilizar caracteres especiales como '=' y ' " ' dentro de la cadena de valores, por ejemplo:

HTML.postheader = "<ul class=\"breadcrumbs\">"

Si una entrada abarca varias líneas, utilice una barra invertida al final de todas las líneas excepto la última:

sourcedirs = kernel tools widgets

Esto puede escribirse como:

sourcedirs = kernel \
             tools \
             widgets

Si un valor abarca varias líneas pero se interpreta como una sola cadena, las líneas se unen con espacios.

Expansión de valores de configuración

QDoc soporta la expansión de variables de entorno dentro de los archivos de configuración. Por ejemplo, los módulos Qt dependen de la variable de entorno QT_INSTALL_DOCS para incluir definiciones relacionadas con todos los proyectos de documentación de módulos Qt:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

Una variable a expandir lleva el prefijo '$'. Para utilizar el carácter literal '$' dentro de una cadena de valores, escápelo con una barra invertida: '\$'.

Desde QDoc 6.0, los valores pueden expandirse también desde otras variables de configuración. Además de la sintaxis $variable, también es válida ${variable}. Esta última elimina la necesidad de separar el nombre de la variable con espacios en blanco o caracteres no variables. Por ejemplo:

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

Si la variable de destino se refiere a una lista de cadenas, se unirán utilizando espacios en el valor expandido:

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

También es posible controlar qué carácter se utiliza para unir la lista de cadenas:

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

Como la expansión se realiza después de leer todas las variables, el orden en el que están definidas no importa.

Expansión de variables de entorno

Cuando se expanden variables de entorno, la sintaxis ${variable} tiene un comportamiento diferente comparado con $variable. La primera expande el contenido de la variable en su lugar para ser analizada como parte del fichero de configuración, mientras que la segunda simplemente asigna el contenido como un valor para la variable de configuración actual. Esto tiene implicaciones si la variable de entorno contiene una lista de elementos separados por espacios en blanco, u otro formato reconocido por QDoc.

Por ejemplo, si el valor de una variable de entorno SRCDIRS es "../src/a ../src/b", entonces

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

Variables de configuración

Lista de variables

• define
• depende
• documentaciónencabeceras
• exampledirs
• ejemplos
• ejemplosrutadeinstalación
• ejemplos.extensionesarchivo
• ejemplos.warnaboutmissingimages
• examples.warnaboutmissingprojectfiles
• excluidosir
• archivos excluidos
• extraimágenes
• falsedades
• headerdirs
• cabeceras
• headers.extensionesarchivo
• HTML.pie
• HTML.postheader
• HTML.postpostheader
• HTML.estilo
• includepaths
• includeprivate
• ignorewords
• ignoresince
• imagedirs
• imagesoutputdir
• índices
• idioma
• locationinfo
• advertencias de registro
• macro
• manifestmeta
• cabecera del módulo
• navegación
• carpeta de salida
• formatos de salida
• outputprefixes
• outputsuffixes
• nombredelproducto
• proyecto
• raíz del proyecto
• sourcedirs
• fuentes
• fuentes.extensionesarchivo
• espurio
• tabsize
• url
• url.ejemplos
• url.fuentes
• usealttextastitle
• versión
• versionesym
• límite de advertencia

Categorías

• Variables de configuración genéricas
• Variables de configuración de formato específico

Ejemplos de archivos de configuración

• Un archivo de configuración mínima: minimum.qdocconf
• El archivo de configuración de Qt: qtgui.qdocconf