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

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

Ответ 1

Посмотрите на команду mainpage.

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

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

Ответ 2

Обратите внимание, что в версии 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 для деталей.

Ответ 3

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

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Ответ 4

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

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

И в вашем Doxyfile:

INPUT = toc.h \

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

Ответ 5

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

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

Ответ 6

Я пробовал все выше с 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.