So erstellen Sie eine Einführungsseite mit Doxygen

102

Ich habe mit Doxygen eine Dokumentation für mein SDK erstellt. Es enthält die Liste der Dateien, Namespaces, Klassen, Typen usw. - alles, was ich als Doxygen-Kommentare in den Code eingefügt habe. Jetzt möchte ich einige allgemeine Informationen über SDK (Art der Einführung) schreiben, die sich nicht direkt auf ein Codeelement beziehen. Ich möchte diese Einführung auf der Startseite der Dokumentation platzieren. Wie kann ich das machen?

Alex F.
quelle

Antworten:

95

Schauen Sie sich den mainpageBefehl an.

Schauen Sie sich auch diese Antwort auf einen anderen Thread an: So fügen Sie benutzerdefinierte Dateien in Doxygen ein . Darin heißt es , dass es drei Erweiterungen sind die Klassen als zusätzliche Dokumentationsdateien doxygen: .dox, .txtund .doc. Dateien mit diesen Erweiterungen werden nicht im Dateiindex angezeigt, können jedoch verwendet werden, um zusätzliche Informationen in Ihre endgültige Dokumentation aufzunehmen. Dies ist sehr nützlich für die Dokumentation, die erforderlich ist, aber nicht wirklich für die Aufnahme in Ihren Quellcode geeignet ist (z. B. eine FAQ).

Daher würde ich empfehlen, eine mainpage.dox(oder ähnlich benannte) Datei in Ihrem Projektverzeichnis zu haben, um Ihnen das SDK vorzustellen. Beachten Sie, dass Sie in diese Datei einen oder mehrere Kommentarblöcke im C / C ++ - Stil einfügen müssen.

Chris
quelle
3
Zumindest Markdown-Dateien ( .mdund .markdown) werden ebenfalls als zusätzliche Dokumentationsdateien betrachtet. Ich bevorzuge sie, .doxweil sie keine umgebenden Codekommentare benötigen und mit einem Markdown-Editor gut bearbeitet werden können - ohne Nachteile.
Pascal
56

Ab Version 1.8.8 gibt es auch die Option USE_MDFILE_AS_MAINPAGE. Stellen Sie also sicher, dass Sie Ihre Indexdatei, z. B. README.md , hinzufügen INPUTund als Wert für diese Option festlegen:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Pascal
quelle
4
Wenn Sie README.md als Hauptseite verwenden möchten, stellen Sie außerdem sicher, dass es in der INPUT-Liste an erster Stelle steht. Wenn es mehrere Mainpage-Kandidaten gibt, wird der erste ausgewählt, der beim Parsen angetroffen wird, oder so scheint es.
Lester Peabody
2
Übrigens müssen Sie in doxygen gui nur Ihre .md-Datei unter Experte> Eingabe> Eingabe einfügen.
Adrian Lopez
USE_MDFILE_AS_MAINPAGEhat bei mir nicht funktioniert. Gemäß der Dokumentation müssen Sie {#mainpage}nach dem Titel des Abschriften-Dokuments einfügen. Das hat funktioniert.
Samvv
2
@samvv Ich habe dem Markdown-Dokument kein Extra hinzugefügt. Ich habe gerade das INPUT = README.mddamals benutzt INPUT += src(um @ Lesters Vorschlag zu folgen) und das USE_MDFILE_AS_MAINPAGE = README.mdund es hat wie ein Zauber funktioniert. Version: $ doxygen --versionkehrt 1.8.11zu mir zurück.
Xavi Montero
1
In Doxygen 1.8.2 hat das einzige, was funktioniert hat, das Hinzufügen von \mainpageinnen (kann dies in einem Kommentar tun (siehe diesen Link zu Kommentaren in MarkDown). Dies hat immer noch den Bereich "Verwandte Seiten" mit einem Platzhalter (leer) erstellt. Das ist ärgerlich, aber Zumindest habe ich die Hauptseite
Evgen
55

Beachten Sie, dass Sie mit Doxygen Release 1.8.0 auch Markdown-formatierte Seiten hinzufügen können. Damit dies funktioniert, müssen Sie Seiten mit einer .mdoder einer .markdownErweiterung erstellen und der Konfigurationsdatei Folgendes hinzufügen:

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

Weitere Informationen finden Sie unter http://www.doxygen.nl/manual/markdown.html#md_page_header .

Sauerstoff
quelle
6
Tatsächlich unterstützt die aktuelle Version 1.8.0 Markdown, behandelt sie jedoch nicht als Dokumentation. So erhalten Sie Markdown-Klassen, die im Abschnitt Dateien und Verzeichnisse aufgeführt sind. Die Lösung besteht darin , Ihre Markdown-Erweiterungen dox=mdals hinzuzufügen EXTENSION_MAPPINGund in umzubenennen. .doxDie Konfiguration sieht also folgendermaßen aus:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
Antitoxic
6
Guter Punkt. Ich werde dies so korrigieren, dass .md und .markdown ähnlich wie .dox behandelt werden.
Sauerstoff
4
Leider endet dies unter "Verwandte Seiten", nicht als Hauptseite
Evgen
7

Die folgende Syntax kann beim Hinzufügen einer Hauptseite und verwandter Unterseiten für Sauerstoff hilfreich sein:

/*! \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"
 */

Das Erstellen von Gruppen wie folgt hilft auch beim Entwerfen von Seiten:

/** \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.
 */

Ein Beispiel finden Sie hier

Birol Capa
quelle
@FelixSFD Vielen Dank für Ihr Feedback. Ich habe meine Antwort entsprechend Ihrer Antwort aktualisiert.
Birol Capa
3

Ich habe all das mit v 1.8.13 ohne Erfolg versucht. Was für mich (unter macOS) funktionierte, war die Verwendung des Tags doxywizard-> Expert, um die USE_MD_FILE_AS_MAINPAGEEinstellung zu füllen .

Es wurden die folgenden Änderungen an meiner Doxy-Datei vorgenommen:

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

Beachten Sie den Zeilenabschluss für INPUT, ich habe gerade Leerzeichen als Trennzeichen verwendet, wie in der Dokumentation angegeben. AFAICT Dies ist die einzige Änderung zwischen der nicht funktionierenden und der funktionierenden Version der Doxy-Datei.

VorpalSword
quelle
1
Klarstellung - doxywizard ist das GUI-Frontend, das unter macOS installiert wird.
VorpalSword
Ich musste \ mainpage hinzufügen, damit README.md als Hauptseite erkannt wurde
JBaczuk