Как сделать вводную страницу с Doxygen

Я сделал документацию для своего SDK, используя Doxygen. Он содержит список файлов, пространств имен, классов, типов и т. Д. - все, что я разместил в качестве комментариев Doxygen в коде. Теперь я хочу написать некоторую общую информацию о SDK (своего рода введение), которая не связана напрямую с каким-либо элементом кода. Я хочу разместить это введение на стартовой странице документации. Как я могу это сделать?

Взгляните на mainpage команду.

Кроме того, посмотрите этот ответ в другой теме: Как включить пользовательские файлы в Doxygen . Он утверждает , что есть три расширения , которые Doxygen классов в качестве дополнительных файлов документации: .dox, .txtи .doc. Файлы с этими расширениями не отображаются в индексе файлов, но могут использоваться для включения дополнительной информации в вашу окончательную документацию - очень полезно для документации, которая необходима, но не совсем подходит для включения в исходный код (например, FAQ)

Поэтому я бы рекомендовал иметь mainpage.doxфайл (или файл с аналогичным именем) в каталоге вашего проекта, чтобы познакомить вас с SDK. Обратите внимание, что внутри этого файла вам нужно поместить один или несколько блоков комментариев в стиле C / C ++.

Начиная с v1.8.8 также есть опция USE_MDFILE_AS_MAINPAGE. Поэтому не забудьте добавить свой индексный файл, например README.md , INPUTи установить его как значение этой опции:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Обратите внимание, что с версией Doxygen 1.8.0 вы также можете добавлять страницы с форматированием Markdown. Чтобы это работало, вам необходимо создать страницы с расширением .mdили .markdownи добавить в файл конфигурации следующее:

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

Подробнее см. Http://www.doxygen.nl/manual/markdown.html#md_page_header .

Следующий синтаксис может помочь при добавлении главной страницы и связанных подстраниц для 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"
 */

Создание следующих групп также помогает при проектировании страниц:

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

Пример можно найти здесь

Добавьте в документацию любой файл, который будет включать ваш контент, например toc.h :

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

И в вашем Doxyfile:

INPUT = toc.h \

Пример (на русском языке):

• scale-tech.ru/luckyBackupW/doc/html/index.html (через web.archive.org)

• scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (через web.archive.org)

Все вышеперечисленное я пробовал с v 1.8.13, но безрезультатно. Что сработало для меня (в macOS), так это использование тега doxywizard-> Expert для заполнения USE_MD_FILE_AS_MAINPAGEнастройки.

Он внес следующие изменения в мой Doxyfile:

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

Обратите внимание на завершение строки INPUT, я только что использовал пробел в качестве разделителя, как указано в документации. AFAICT, это единственное различие между неработающей и рабочей версией Doxyfile.