Я сделал документацию для своего SDK, используя Doxygen. Он содержит список файлов, пространств имен, классов, типов и т. Д. - все, что я разместил в качестве комментариев Doxygen в коде. Теперь я хочу написать некоторую общую информацию о SDK (своего рода введение), которая не связана напрямую с каким-либо элементом кода. Я хочу разместить это введение на стартовой странице документации. Как я могу это сделать?
Ответы:
Взгляните на mainpage команду.
Кроме того, посмотрите этот ответ в другой теме: Как включить пользовательские файлы в Doxygen . Он утверждает , что есть три расширения , которые Doxygen классов в качестве дополнительных файлов документации: .dox, .txtи .doc. Файлы с этими расширениями не отображаются в индексе файлов, но могут использоваться для включения дополнительной информации в вашу окончательную документацию - очень полезно для документации, которая необходима, но не совсем подходит для включения в исходный код (например, FAQ)
Поэтому я бы рекомендовал иметь mainpage.doxфайл (или файл с аналогичным именем) в каталоге вашего проекта, чтобы познакомить вас с SDK. Обратите внимание, что внутри этого файла вам нужно поместить один или несколько блоков комментариев в стиле C / C ++.
.mdи .markdown) также считаются дополнительными файлами документации. Я предпочитаю их, .doxпотому что они не нуждаются в комментариях к коду и могут быть легко отредактированы с помощью редактора разметки - без недостатков.
Начиная с v1.8.8 также есть опция USE_MDFILE_AS_MAINPAGE. Поэтому не забудьте добавить свой индексный файл, например README.md , INPUTи установить его как значение этой опции:
INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
USE_MDFILE_AS_MAINPAGEу меня не сработало. Согласно документации, вы должны указать {#mainpage}после заголовка документа уценки. Это сработало.
INPUT = README.mdthen INPUT += src(чтобы последовать предложению @ Lester) и, USE_MDFILE_AS_MAINPAGE = README.mdи это сработало как шарм. Версия: $ doxygen --versionвозвращается 1.8.11ко мне.
\mainpageвнутри (можно сделать это в комментарии (см. Эту ссылку о комментариях в MarkDown). Это все еще создает область связанных страниц с заполнителем (пустым). Это раздражает, но по крайней мере, я получил главную страницу
Обратите внимание, что с версией 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 .
dox=mdкак EXTENSION_MAPPINGи переименовать расширение уценки в .dox.so конфиг будет выглядеть следующим образом :INPUT += your_page.dox EXTENSION_MAPPING += dox=md
Следующий синтаксис может помочь при добавлении главной страницы и связанных подстраниц для 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 \
Пример (на русском языке):
Все вышеперечисленное я пробовал с 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.