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 cubre las distintas variables de configuración con mayor detalle.

Archivos de configuración de QDoc

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

QDoc tiene dos salidas: documentación HTML y documentación en formato DocBook XML. La principal diferencia entre las dos salidas es que la documentación HTML necesita tener su información de estilo HTML en los archivos de configuración. La documentación DocBook no, y un proceso separado puede dar estilo a la documentación en DocBook en un momento posterior. Por lo tanto, DocBook es más flexible al permitir que se apliquen diferentes estilos a la misma información.

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

qdoc project.qdocconf

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

Información sobre el 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

La especificación de la ruta a los directorios de origen permite a QDoc encontrar las fuentes 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á cabeceras y fuentes de las especificadas 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 estar en archivos de configuración separados para modular la construcción de la documentación.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

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

Archivos adicionales

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

HTML.extraimages = extraImage.png \
                   extraImage2.png

Los archivos extraImage.png y extraImage2.png se copiarán en el directorio de salida HTML.

Qt Help Configuración del marco de trabajo

QDoc también exportará un archivo de proyectoQt Help , en un archivo qhp. El archivo qhp es entonces utilizado por el qhelpgenerator para empaquetar la documentación en un archivo qch. Qt Creator y Qt Assistant lee el archivo qch para mostrar la documentación.

El artículo Creación de archivos de proyecto de ayuda cubre las opciones de configuración.

Configuración HTML

QDoc dispone de un generador HTML que exportará un conjunto de documentación a archivos HTML utilizando varias opciones 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 plantillas para generar HTML. Normalmente, el directorio de plantillas contiene un directorio scripts, images, y un directorio style, que contiene 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 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 con objetivos de otros proyectos especificando un conjunto de dependencias o un conjunto de rutas directas a los archivos de índice de los que depende el proyecto. Cuando QDoc genera documentación para un proyecto, también genera un archivo .index que contiene las direcciones URL de cada entidad vinculable del proyecto. Otros proyectos pueden definir una dependencia del archivo de índice para enlazar con la documentación de ese proyecto.

Véase también: dependencias e índices.

Macros y otras configuraciones

Existen macros para sustituir caracteres HTML y son útiles para generar caracteres HTML válidos específicos.

macro.pi.HTML         = "Π"

El fragmento de código sustituirá cualquier instancia de \\pi por &Pi; en el archivo HTML, que aparecerá como el símbolo griego Π cuando se visualice en los navegadores.

Véase también: macro.

Complementos de QML

QDoc es capaz de analizar archivos QML en busca de comentarios QDoc. QDoc analizará 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 tener un prefijo y un sufijo a continuación del nombre del módulo QML, especificados en el archivo de configuración de QDoc.

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

Véase también: outputprefixes, outputsuffixes.