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


102

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?


Respuestas:


95

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


3
Al menos los archivos de rebajas ( .mdy .markdown) también se consideran archivos de documentación adicionales. Los prefiero .doxporque no necesitan comentarios de código circundantes y pueden editarse muy bien con un editor de rebajas, sin inconvenientes.
Pascal

56

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

4
Además de esto, si va a utilizar README.md como página principal, asegúrese de que aparezca primero en la lista INPUT. Cuando hay varios candidatos para la página principal, se selecciona el primero que se encuentra durante el análisis, o eso parece.
Lester Peabody

2
Por cierto, en la interfaz gráfica de usuario de doxygen solo tienes que incluir tu archivo .md en experto> entrada> entrada.
Adrian Lopez

USE_MDFILE_AS_MAINPAGEno funcionó para mí. De acuerdo con la documentación, debe incluir {#mainpage}después del título del documento de rebajas. Esto funcionó.
samvv

2
@samvv No agregué ningún extra al documento de rebajas. Solo usé el INPUT = README.mdentonces INPUT += src(para seguir la sugerencia de @ Lester) y USE_MDFILE_AS_MAINPAGE = README.mdfuncionó a las mil maravillas. Versión: $ doxygen --versionvuelve 1.8.11a mí.
Xavi Montero

1
En Doxygen 1.8.2, lo único que funcionó fue agregar \mainpageadentro (puede hacerlo en un comentario (vea este enlace sobre comentarios en MarkDown). Esto aún creó el área de Páginas relacionadas, con un marcador de posición (vacío). Eso es molesto, pero al menos tengo la página principal
Evgen

55

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.


6
En realidad, la rebaja de soporte de la versión 1.8.0 actual, PERO no los trata como documentación. Por lo tanto, terminará con clases de rebajas enumeradas en la sección Archivos y directorios. La solución es agregar dox=mdcomo una EXTENSION_MAPPINGy cambiar el nombre de sus extensiones de rebajas a .dox. De modo que la configuración se verá así:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
antitóxico

6
Buen punto. Corregiré esto de manera que .md y .markdown se traten de manera similar a .dox.
Doxygen

4
Desafortunadamente, esto termina en Páginas relacionadas, no como la página principal
Evgen

7

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í


@FelixSFD gracias por sus comentarios. Actualicé mi respuesta de acuerdo con su respuesta.
Birol Capa

5

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):


1
Los vínculos de escala-tecnología están muertos ahora.
Ben Fulton

3

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.


1
aclaración: doxywizard es la interfaz gráfica de usuario que se instala en macOS.
VorpalSword

Tuve que agregar \ mainpage para que README.md fuera reconocido como la página principal
JBaczuk
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.