Як зробити сторінку вступу за допомогою 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. Для цього вам потрібно створити сторінки з a .mdабо .markdownрозширенням та додати наступне до конфігураційного файлу:

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

Докладніше див. У http://www.doxygen.nl/manual/markdown.html#md_page_header .

Наступний синтаксис може допомогти додати головну сторінку та пов’язані підсторінки доксигену:

/*! \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, я щойно використовував простір як роздільник, як зазначено в документації. АФАКТИЧНО - це єдина зміна між непрацюючою та робочою версією Doxyfile.