So erstellen Sie eine Einführungsseite mit Doxygen

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?

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.

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

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 .

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

Fügen Sie eine beliebige Datei in die Dokumentation ein, die Ihren Inhalt enthält, z. B. toc.h :

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

Und in deinem Doxyfile:

INPUT = toc.h \

Beispiel (auf Russisch):

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

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

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.