Come creare una pagina introduttiva con Doxygen


102

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?


Risposte:


95

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


3
Almeno i file markdown ( .mde .markdown) sono considerati anche file di documentazione aggiuntivi. Li preferisco .doxperché non hanno bisogno di commenti sul codice circostanti e possono essere ben modificati con un editor di markdown, senza inconvenienti.
Pascal

56

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

4
Oltre a questo, se intendi utilizzare README.md come pagina principale, assicurati che sia il primo nell'elenco INPUT. Quando sono presenti più candidati per la pagina principale, viene selezionato il primo incontrato durante l'analisi, o almeno così sembra.
Lester Peabody

2
A proposito, nella gui di doxygen devi solo includere il tuo file .md sotto expert> input> input.
Adrian Lopez

USE_MDFILE_AS_MAINPAGENon ha funzionato per me. Secondo la documentazione, è necessario includere {#mainpage}dopo il titolo del documento di ribasso. Questo ha funzionato.
samvv

2
@samvv Non ho aggiunto alcun extra al documento markdown. Ho appena usato INPUT = README.mdthen INPUT += src(per seguire il suggerimento di @ Lester) e il USE_MDFILE_AS_MAINPAGE = README.mde ha funzionato a meraviglia. Versione: $ doxygen --versionritorna 1.8.11a me.
Xavi Montero

1
In Doxygen 1.8.2, l'unica cosa che ha funzionato è stata l'aggiunta di \mainpageinterni (è possibile farlo in un commento (vedere questo collegamento sui commenti in MarkDown). Questo creava comunque un'area delle pagine correlate, con un segnaposto (vuoto). È fastidioso, ma almeno ho ottenuto la pagina principale
Evgen

55

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.


6
In realtà l'attuale versione 1.8.0 supporta il markdown MA non li tratta come documentazione. Quindi ti ritroverai con le classi di markdown elencate nella sezione File e directory. La soluzione è aggiungere dox=mdcome EXTENSION_MAPPINGe rinominare le estensioni di .doxmarkdown in . Quindi la configurazione sarà simile a:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
antitossico

6
Buon punto. Lo correggerò in modo tale che .md e .markdown siano trattati in modo simile a .dox.
doxygen

4
Sfortunatamente, questo finisce nelle Pagine correlate, non come la pagina principale
Evgen

7

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


@FelixSFD grazie per il tuo feedback. Ho aggiornato la mia risposta in base alla tua risposta.
Birol Capa

5

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


1
I collegamenti tecnologici in scala sono morti ora.
Ben Fulton

3

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.


1
chiarimento - doxywizard è il front-end della GUI che si installa su macOS.
VorpalSword

Ho dovuto aggiungere \ mainpage per far sì che README.md fosse riconosciuto come mainpage
JBaczuk
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.