En esta página

Creación de archivos de configuración de QDoc

Para generar documentación, QDoc utiliza archivos de configuración, con la extensión qdocconf, para almacenar los ajustes de configuración.

El artículo «El archivo de configuración de QDoc » trata con mayor detalle las distintas variables de configuración.

Archivos de configuración de QDoc

Los ajustes de configuración de QDoc pueden residir en un único archivo qdocconf, pero también pueden encontrarse en otros archivos qdocconf. El comando « include(<filepath>) » permite que los archivos de configuración incluyan otros archivos de configuración.

QDoc genera dos tipos de salida: documentación en HTML y documentación en formato DocBook XML. La principal diferencia entre ambas salidas es que la documentación HTML requiere que la información de estilo HTML se incluya en los archivos de configuración. La documentación DocBook no la necesita, y se puede aplicar el estilo a la documentación DocBook posteriormente mediante un proceso independiente. Por lo tanto, DocBook es más flexible a la hora de permitir que se apliquen diferentes estilos a la misma información.

Para ejecutar QDoc, se proporciona el archivo de configuración del proyecto como argumento.

qdoc project.qdocconf

La configuración del proyecto contiene información que QDoc utiliza para crear la documentación.

Información del proyecto

QDoc utiliza la información de project para generar la documentación.

project = QDoc Project
description = Sample QDoc project

Directorios de entrada y salida

Al especificar la ruta a los directorios de origen, QDoc puede localizar los archivos de origen y generar la documentación.

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc procesará los archivos de cabecera y de código fuente indicados en la variable fileextensions.

Del mismo modo, QDoc necesita la ruta al directorio de salida. La variable outputformats determina el tipo de documentación. Estas variables deben figurar en archivos de configuración independientes para modularizar la compilación de la documentación.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc puede resolver las rutas relativas al archivo `qdocconf`, así como a las variables de entorno.

Nota: Durante cada ejecución de QDoc, se elimina el directorio de salida.

Archivos adicionales

QDoc guardará la documentación generada en el directorio especificado como directorio de salida. También es posible especificar archivos adicionales que QDoc deba exportar.

HTML.extraimages = extraImage.png \
                   extraImage2.png

Los archivos « extraImage.png » y « extraImage2.png » se copiarán al directorio de salida HTML.

Qt Help Configuración del marco de trabajo

QDoc también exportará un archivo de proyecto deQt Help , en un archivo qhp. A continuación, el qhelpgenerator utiliza el archivo qhp para empaquetar la documentación en un archivo qch. Qt Creator y Qt Assistant leen el archivo qch para mostrar la documentación.

El artículo «Creación de archivos de proyecto de ayuda » describe las opciones de configuración.

Configuración de HTML

QDoc cuenta con un generador de HTML que exporta un conjunto de documentación a archivos HTML utilizando diversos parámetros de configuración. QDoc colocará la documentación generada en el directorio especificado por la variable ` outputdir `.

outputformats = HTML
outputdir =  <path to output directory>

QDoc necesita saber dónde se encuentran los estilos y las plantillas para generar HTML. Normalmente, el directorio de plantillas contiene los directorios « scripts », « images » y « style », que contienen scripts y archivos CSS.

Las principales variables de configuración son:

HTML.postheader
HTML.postpostheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

La variable HTML.headerstyles inserta la información de estilo en el archivo HTML y la variable HTML.stylesheets especifica qué archivos debe copiar QDoc en el directorio de salida. Además, QDoc incrustará la cadena de las variables postheader, footer y otras relacionadas en cada archivo HTML.

El artículo «Variables de configuración específicas del formato » describe el uso de cada variable.

Archivos de índice de QDoc

Los proyectos de documentación pueden enlazar a elementos de otros proyectos especificando un conjunto de dependencias o una serie de rutas directas a los archivos de índice de los que depende este proyecto. Cuando QDoc genera la documentación de un proyecto, también genera un archivo .index que contiene las URL de cada entidad enlazable del proyecto. Otros proyectos pueden entonces definir una dependencia con respecto al archivo de índice para enlazar con la documentación de ese proyecto.

Véase también: depends e indexes.

Macros y otras configuraciones

Existen macros para sustituir caracteres HTML que resultan útiles para generar caracteres específicos válidos en HTML.

macro.pi.HTML         = "&Pi;"

El fragmento de código sustituirá cualquier aparición de « \\pi » por « &Pi » en el archivo HTML, lo que aparecerá como el símbolo griego Π al visualizarse en los navegadores.

Véase también: macro.

Novedades de QML

QDoc es capaz de analizar archivos QML en busca de comentarios QDoc. QDoc analizará los archivos con la extensión QML ( .qml) si el tipo de extensión está incluido en la variable «fileextensions ».

Además, los archivos HTML generados pueden incluir un prefijo y un sufijo tras el nombre del módulo QML, tal y como se especifica en el archivo de configuración de QDoc.

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

Véase también: outputprefixes, outputsuffixes.

© 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.