Jak stworzyć stronę wprowadzającą w Doxygen

Zrobiłem dokumentację dla mojego SDK, używając Doxygen. Zawiera listę plików, przestrzeni nazw, klas, typów itp. - wszystko co umieściłem jako komentarze Doxygen w kodzie. Teraz chcę napisać ogólne informacje o SDK (rodzaj wprowadzenia), które nie są związane bezpośrednio z żadnym elementem kodu. Chcę umieścić to wprowadzenie na stronie startowej dokumentacji. W jaki sposób mogę to zrobić?

Spójrz na mainpagepolecenie.

Spójrz także na tę odpowiedź w innym wątku: Jak dołączyć własne pliki do Doxygen . Stwierdza, że istnieją trzy rozszerzenia, które jako dodatkowe zajęcia doxygen plików Dokumentacja: .dox, .txti .doc. Pliki z tymi rozszerzeniami nie pojawiają się w indeksie plików, ale można ich użyć do dołączenia dodatkowych informacji do ostatecznej dokumentacji - bardzo przydatne w przypadku dokumentacji, która jest niezbędna, ale nie jest tak naprawdę odpowiednia do dołączenia do kodu źródłowego (na przykład FAQ)

Dlatego zalecałbym posiadanie mainpage.dox(lub podobnie nazwanego) pliku w katalogu projektu, aby wprowadzić zestaw SDK. Zauważ, że w tym pliku musisz umieścić jeden lub więcej bloków komentarzy w stylu C / C ++.

Od wersji 1.8.8 dostępna jest również opcja USE_MDFILE_AS_MAINPAGE. Więc pamiętaj, aby dodać swój plik indeksu, np. README.md , do INPUTi ustawić go jako wartość tej opcji:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Zauważ, że w Doxygen w wersji 1.8.0 możesz także dodawać sformatowane strony Markdown. Aby to zadziałało, musisz utworzyć strony z rozszerzeniem .mdlub .markdowni dodać do pliku konfiguracyjnego:

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

Szczegółowe informacje można znaleźć pod adresem http://www.doxygen.nl/manual/markdown.html#md_page_header .

Poniższa składnia może pomóc w dodaniu strony głównej i powiązanych podstron dla 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"
 */

Tworzenie grup w następujący sposób również pomaga w projektowaniu stron:

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

Przykład można znaleźć tutaj

Dodaj dowolny plik w dokumentacji, który będzie zawierał Twoją treść, na przykład toc.h :

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

A w twoim Doxyfile:

INPUT = toc.h \

Przykład (po rosyjsku):

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

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

Próbowałem wszystkich powyższych rozwiązań w wersji 1.8.13 bezskutecznie. To, co zadziałało dla mnie (na macOS), to użycie tagu doxywizard-> Expert do wypełnienia USE_MD_FILE_AS_MAINPAGEustawienia.

Wprowadził następujące zmiany w moim Doxyfile:

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

Zwróć uwagę na zakończenie linii dla INPUT, właśnie użyłem spacji jako separatora, jak określono w dokumentacji. ODPOWIEDŹ to jedyna zmiana między niedziałającą i działającą wersją Doxyfile.