Cara membuat halaman pengantar dengan Doxygen

Saya membuat dokumentasi untuk SDK saya, menggunakan Doxygen. Ini berisi daftar file, ruang nama, kelas, jenis dll - semua yang saya tempatkan sebagai komentar Doxygen dalam kode. Sekarang saya ingin menulis beberapa informasi umum tentang SDK (jenis pengenalan), yang tidak terkait langsung dengan elemen kode apa pun. Saya ingin menempatkan pendahuluan ini di halaman awal dokumentasi. Bagaimana saya bisa melakukan ini?

Lihat mainpageperintahnya.

Juga, lihat jawaban ini di utas lain: Cara menyertakan file khusus di Doxygen . Ini menyatakan bahwa ada tiga ekstensi yang Doxygen kelas sebagai file dokumentasi tambahan: .dox, .txtdan .doc. File dengan ekstensi ini tidak muncul di indeks file tetapi dapat digunakan untuk memasukkan informasi tambahan ke dalam dokumentasi akhir Anda - sangat berguna untuk dokumentasi yang diperlukan tetapi tidak terlalu sesuai untuk disertakan dengan kode sumber Anda (misalnya, FAQ)

Jadi saya akan merekomendasikan memiliki file mainpage.dox(atau bernama serupa) di direktori proyek Anda untuk memperkenalkan Anda SDK. Perhatikan bahwa di dalam file ini Anda perlu meletakkan satu atau lebih blok komentar gaya C / C ++.

Mulai v1.8.8 juga ada opsi USE_MDFILE_AS_MAINPAGE. Jadi pastikan untuk menambahkan file indeks Anda, misalnya README.md , ke INPUTdan setel sebagai nilai opsi ini:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Perhatikan bahwa dengan Doxygen rilis 1.8.0 Anda juga dapat menambahkan halaman berformat penurunan harga. Agar ini berfungsi, Anda perlu membuat halaman dengan ekstensi .mdatau .markdown, dan menambahkan yang berikut ini ke file konfigurasi:

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

Lihat http://www.doxygen.nl/manual/markdown.html#md_page_header untuk detailnya.

Sintaks berikut dapat membantu untuk menambahkan halaman utama dan subhalaman terkait untuk 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"
 */

Membuat grup sebagai berikut juga membantu mendesain halaman:

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

Contohnya dapat ditemukan di sini

Tambahkan file apa pun dalam dokumentasi yang akan menyertakan konten Anda, misalnya toc.h :

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

Dan di Doxyfile:

INPUT = toc.h \

Contoh (dalam bahasa Rusia):

• scale-tech.ru/luckyBackupW/doc/html/index.html (melalui web.archive.org)

• scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (melalui web.archive.org)

Saya mencoba semua hal di atas dengan v 1.8.13 tetapi tidak berhasil. Apa yang berhasil untuk saya (di macOS) adalah menggunakan tag doxywizard-> Expert untuk mengisi USE_MD_FILE_AS_MAINPAGEpengaturan.

Itu membuat perubahan berikut pada Doxyfile saya:

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

Perhatikan penghentian baris karena INPUT, saya baru saja menggunakan spasi sebagai pemisah seperti yang ditentukan dalam dokumentasi. AFAICT ini adalah satu-satunya perubahan antara versi Doxyfile yang tidak berfungsi dan berfungsi.