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

103

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

Алекс Ф
источник

Ответы:

95

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

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

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

Крис
источник
3
По крайней мере, файлы уценки ( .mdи .markdown) также считаются дополнительными файлами документации. Я предпочитаю их, .doxпотому что они не нуждаются в комментариях к коду и могут быть легко отредактированы с помощью редактора разметки - без недостатков.
Паскаль
56

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

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Паскаль
источник
4
В дополнение к этому, если вы собираетесь использовать README.md в качестве главной страницы, убедитесь, что он стоит первым в списке INPUT. Когда есть несколько кандидатов на главную страницу, выбирается первый, обнаруженный во время синтаксического анализа, по крайней мере, так кажется.
Лестер Пибоди
2
Кстати, в doxygen gui вам нужно только включить ваш .md файл в expert> input> input.
Адриан Лопес,
USE_MDFILE_AS_MAINPAGEу меня не сработало. Согласно документации, вы должны указать {#mainpage}после заголовка документа уценки. Это сработало.
samvv
2
@samvv Я не добавлял ничего лишнего в документ уценки. Я просто использовал INPUT = README.mdthen INPUT += src(чтобы последовать предложению @ Lester) и, USE_MDFILE_AS_MAINPAGE = README.mdи это сработало как шарм. Версия: $ doxygen --versionвозвращается 1.8.11ко мне.
Xavi Montero
1
В Doxygen 1.8.2 единственное, что работало, - это добавление \mainpageвнутри (можно сделать это в комментарии (см. Эту ссылку о комментариях в MarkDown). Это все еще создает область связанных страниц с заполнителем (пустым). Это раздражает, но по крайней мере, я получил главную страницу
Evgen
55

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

доксиген
источник
6
На самом деле текущая версия 1.8.0 поддерживает уценку, НО не рассматривает их как документацию. Таким образом, вы получите классы уценки, перечисленные в разделе «Файлы и каталоги». Решение заключается в добавлении dox=mdкак EXTENSION_MAPPINGи переименовать расширение уценки в .dox.so конфиг будет выглядеть следующим образом :INPUT += your_page.dox EXTENSION_MAPPING += dox=md
антитоксический
6
Хорошая точка зрения. Я исправлю это так, чтобы .md и .markdown обрабатывались аналогично .dox.
doxygen
4
К сожалению, эта страница попадает в раздел "Связанные страницы", а не на главную страницу
Evgen
7

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

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

Бирол Капа
источник
@FelixSFD благодарим вас за отзыв. Я обновил свой ответ в соответствии с вашим ответом.
Бирол Капа,
5

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

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

И в вашем Doxyfile:

INPUT = toc.h \

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

Денис
источник
1
Связи масштабных технологий теперь мертвы.
Бен Фултон
3

Все вышеперечисленное я пробовал с 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.

VorpalSword
источник
1
Уточнение - doxywizard - это интерфейс с графическим интерфейсом, который устанавливается на macOS.
VorpalSword
Мне пришлось добавить \ mainpage, чтобы README.md был признан
главной страницей