Come creare una pagina introduttiva con Doxygen

Ho realizzato la documentazione per il mio SDK, utilizzando Doxygen. Contiene l'elenco di file, spazi dei nomi, classi, tipi ecc. - Tutto ciò che ho inserito come commenti Doxygen nel codice. Ora voglio scrivere alcune informazioni generali sull'SDK (tipo di introduzione), che non è correlato direttamente a nessun elemento di codice. Voglio inserire questa introduzione nella pagina iniziale della documentazione. Come posso fare questo?

Dai un'occhiata al file mainpage comando.

Inoltre, dai un'occhiata a questa risposta a un altro thread: Come includere file personalizzati in Doxygen . Essa afferma che ci sono tre estensioni che Doxygen classi file di documentazione aggiuntivi: .dox, .txte .doc. I file con queste estensioni non vengono visualizzati nell'indice dei file ma possono essere utilizzati per includere informazioni aggiuntive nella documentazione finale - molto utile per la documentazione necessaria ma che non è propriamente appropriata da includere nel codice sorgente (ad esempio, una FAQ)

Quindi consiglierei di avere un file mainpage.dox(o con un nome simile) nella directory del progetto per introdurre l'SDK. Nota che all'interno di questo file devi inserire uno o più blocchi di commenti in stile C / C ++.

A partire dalla v1.8.8 c'è anche l'opzione USE_MDFILE_AS_MAINPAGE. Quindi assicurati di aggiungere il tuo file indice, ad esempio README.md , a INPUTe impostalo come valore di questa opzione:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Nota che con la versione 1.8.0 di Doxygen puoi anche aggiungere pagine formattate Markdown. Affinché funzioni, è necessario creare pagine con estensione .mdo .markdowne aggiungere quanto segue al file di configurazione:

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

Vedi http://www.doxygen.nl/manual/markdown.html#md_page_header per i dettagli.

La seguente sintassi può essere utile per aggiungere una pagina principale e le relative sottopagine per 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"
 */

La creazione di gruppi come segue aiuta anche per la progettazione di pagine:

/** \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 esempio può essere trovato qui

Aggiungi qualsiasi file nella documentazione che includerà il tuo contenuto, ad esempio toc.h :

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

E nel tuo Doxyfile:

INPUT = toc.h \

Esempio (in russo):

• scale-tech.ru/luckyBackupW/doc/html/index.html (tramite web.archive.org)

• scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (tramite web.archive.org)

Ho provato tutto quanto sopra con v 1.8.13 senza alcun risultato. Quello che ha funzionato per me (su macOS) è stato utilizzare il tag doxywizard-> Expert per riempire l' USE_MD_FILE_AS_MAINPAGEimpostazione.

Ha apportato le seguenti modifiche al mio Doxyfile:

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

Nota la terminazione di riga per INPUT, avevo appena usato lo spazio come separatore come specificato nella documentazione. AFAICT questo è l'unico cambiamento tra la versione non funzionante e quella funzionante del Doxyfile.