Cómo hacer una página de introducción con Doxygen

Hice documentación para mi SDK, usando Doxygen. Contiene la lista de archivos, espacios de nombres, clases, tipos, etc., todo lo que puse como comentarios de Doxygen en el código. Ahora quiero escribir información general sobre SDK (una especie de introducción), que no está relacionada directamente con ningún elemento de código. Quiero colocar esta introducción en la página de inicio de la documentación. ¿Cómo puedo hacer esto?

Eche un vistazo al mainpagecomando.

Además, eche un vistazo a esta respuesta a otro hilo: Cómo incluir archivos personalizados en Doxygen . Se afirma que hay tres extensiones, que Doxygen clases como archivos de documentación adicional: .dox, .txty .doc. Los archivos con estas extensiones no aparecen en el índice de archivos, pero se pueden usar para incluir información adicional en su documentación final; muy útil para la documentación que es necesaria pero que no es realmente apropiada para incluir con su código fuente (por ejemplo, una pregunta frecuente)

Por lo tanto, recomendaría tener un mainpage.doxarchivo (o con un nombre similar) en el directorio de su proyecto para presentarle el SDK. Tenga en cuenta que dentro de este archivo debe colocar uno o más bloques de comentarios de estilo C / C ++.

A partir de v1.8.8 también existe la opción USE_MDFILE_AS_MAINPAGE. Así que asegúrese de agregar su archivo de índice, por ejemplo , README.md , INPUTy configúrelo como el valor de esta opción:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Tenga en cuenta que con la versión 1.8.0 de Doxygen también puede agregar páginas con formato Markdown. Para que esto funcione, debe crear páginas con una extensión .mdo .markdowny agregar lo siguiente al archivo de configuración:

INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown

Consulte http://www.doxygen.nl/manual/markdown.html#md_page_header para obtener más detalles.

La siguiente sintaxis puede ayudar a agregar una página principal y subpáginas relacionadas para doxygen:

/*! \mainpage Drawing Shapes
 *
 * This project helps user to draw shapes.
 * Currently two types of shapes can be drawn:
 * - \subpage drawingRectanglePage "How to draw rectangle?"
 *
 * - \subpage drawingCirclePage "How to draw circle?"
 *
 */ 

/*! \page drawingRectanglePage How to draw rectangle?
 *
 * Lorem ipsum dolor sit amet
 *
 */

/*! \page drawingCirclePage How to draw circle?
 *
 * This page is about how to draw a circle.
 * Following sections describe circle:
 * - \ref groupCircleDefinition "Definition of Circle"
 * - \ref groupCircleClass "Circle Class"
 */

Crear grupos de la siguiente manera también ayuda a diseñar páginas:

/** \defgroup groupCircleDefinition Circle Definition
 * A circle is a simple shape in Euclidean geometry.
 * It is the set of all points in a plane that are at a given distance from a given point, the centre;
 * equivalently it is the curve traced out by a point that moves so that its distance from a given point is constant.
 * The distance between any of the points and the centre is called the radius.
 */

Un ejemplo puede ser encontrado aquí

Agregue cualquier archivo en la documentación que incluya su contenido, por ejemplo toc.h :

@ mainpage Manual SDK
<hr/>
@ section pageTOC Content
  -# @ref Description
  -# @ref License
  -# @ref Item
...

Y en tu Doxyfile:

INPUT = toc.h \

Ejemplo (en ruso):

• scale-tech.ru/luckyBackupW/doc/html/index.html (a través de web.archive.org)

• scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (a través de web.archive.org)

Intenté todo lo anterior con v 1.8.13 sin éxito. Lo que funcionó para mí (en macOS) fue usar la etiqueta doxywizard-> Expert para completar la USE_MD_FILE_AS_MAINPAGEconfiguración.

Hizo los siguientes cambios en mi Doxyfile:

USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT                  = ../README.md \
                         ../sdk/include \
                         ../sdk/src

Tenga en cuenta la terminación de la línea para INPUT, acababa de usar el espacio como separador como se especifica en la documentación. AFAICT este es el único cambio entre la versión que no funciona y la que funciona del Doxyfile.