Creación de archivos de proyecto de ayuda

Visión general

Qt Assistant utiliza un sistema para gestionar la documentación de Qt que requiere que QDoc genere inventarios de archivos.

QDoc permite utilizar variables de configuración para especificar qué páginas se van a utilizar en cada conjunto de documentación que genera. Éstas se especifican como subvariables de la variable qhp y cada conjunto se declara utilizando un identificador único como subvariable.

Por ejemplo, el archivo de configuración para el conjunto de documentación Qt Quick especifica información sobre el conjunto como subvariables con el prefijo qhp.QtQuick:

qhp.projects = QtQuick

qhp.QtQuick.file                = qtquick.qhp
qhp.QtQuick.namespace           = org.qt-project.qtquick.$QT_VERSION_TAG
qhp.QtQuick.virtualFolder       = qtquick
qhp.QtQuick.indexTitle          = Qt Quick
qhp.QtQuick.indexRoot           =

qhp.QtQuick.subprojects         = qmltypes classes examples

qhp.QtQuick.subprojects.qmltypes.title = QML Types
qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types
qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass
qhp.QtQuick.subprojects.qmltypes.sortPages = true

qhp.QtQuick.subprojects.classes.title = Classes
qhp.QtQuick.subprojects.classes.title = C++ Classes
qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes
qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
qhp.QtQuick.subprojects.classes.sortPages = true

qhp.QtQuick.subprojects.examples.title = Examples
qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials
qhp.QtQuick.subprojects.examples.selectors = fake:example

El conjunto de documentación puede incluir uno o más subproyectos, que se añaden a la tabla de contenidos con el nombre especificado por title. La página de la documentación a la que hace referencia indexTitle actúa como página índice del subproyecto. Los tipos de página que se incluyen en el subproyecto se especifican en selectors. Las entradas se ordenan alfabéticamente si sortPages se establece en true.

Uso de selectores

La propiedad selectors especifica qué tipos de página se listan bajo la entrada del índice de un subproyecto. Se pueden listar múltiples selectores, separados por espacios en blanco.

Subtipos disponibles para el selector doc:

Por ejemplo, la siguiente configuración seleccionaría páginas de ejemplo y páginas que incluyan el comando \ingroup tutorials:

qhp.QtQuickControls.subprojects = examples
qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials
qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials
qhp.QtQuickControls.subprojects.examples.sortPages = true

Añadir tabla de contenidos

Para crear una tabla de contenidos para un manual, cree un subproyecto con una propiedad type y ajústela a manual. La página de la documentación a la que hace referencia la propiedad indexTitle debe contener una lista de enlaces que actúe como tabla de contenidos para todo el manual. QDoc tomará la información de esta lista y creará una tabla de contenidos para el subproyecto.

Por ejemplo, el archivo de configuración de Qt Creator define un único subproyecto para su documentación, incluyendo toda la documentación en un único manual:

qhp.QtCreator.subprojects = manual
qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
qhp.QtCreator.subprojects.manual.indexTitle = All topics
qhp.QtCreator.subprojects.manual.type = manual

En este ejemplo, la página titulada "Todos los temas" contiene una lista anidada de enlaces a páginas de la documentación que se duplica en la pestaña Contenidos de Qt Assistant.

Ejemplo de estructura de lista:

/*!
    \page qtcreator-toc.html
    \title All topics

    \list
        \li \l {Installation}
        \li \l {Getting started}
        \list
            \li \l {Configuring Qt Creator}
            \li \l {Building and running an example}
        \endlist
        \li \l {Overview}
        \li \l {Tutorials}
            \generatelist tutorials
        ...
    \endlist
*/

Arriba, el tema "Primeros pasos " tiene dos páginas como subtemas. El tema Tutoriales es una página \group y se utiliza un comando \generatelist para listar páginas de tutoriales individuales (miembros del grupo tutorials ) como subtemas.