Cara membuat halaman pengantar dengan Doxygen

102

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?

Alex F
sumber

Jawaban:

95

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 ++.

Chris
sumber
3
Setidaknya file penurunan harga ( .mddan .markdown) dianggap sebagai file dokumentasi tambahan juga. Saya lebih suka mereka .doxkarena mereka tidak membutuhkan komentar kode sekitarnya dan dapat diedit dengan baik dengan editor penurunan harga - tanpa kekurangan.
Pascal
56

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
Pascal
sumber
4
Selain itu, jika Anda akan menggunakan README.md sebagai halaman utama, pastikan halaman itu muncul pertama kali dalam daftar INPUT. Jika ada beberapa kandidat halaman utama, yang pertama ditemukan saat penguraian dipilih, atau begitulah tampaknya.
Lester Peabody
2
Ngomong-ngomong, di doxygen gui Anda hanya perlu memasukkan file .md Anda di bawah expert> input> input.
Adrian Lopez
USE_MDFILE_AS_MAINPAGEtidak bekerja untuk saya. Menurut dokumentasi, Anda harus menyertakan {#mainpage}setelah judul dokumen penurunan harga. Ini berhasil.
samvv
2
@samvv Saya tidak menambahkan tambahan apapun ke dokumen penurunan harga. Saya hanya menggunakan INPUT = README.mdlalu INPUT += src(untuk mengikuti saran @ Lester) USE_MDFILE_AS_MAINPAGE = README.mddan itu bekerja seperti pesona. Versi: $ doxygen --versionkembali 1.8.11ke saya.
Xavi Montero
1
Di Doxygen 1.8.2, satu-satunya hal yang berhasil adalah menambahkan \mainpagedi dalam (dapat melakukannya di komentar (lihat tautan ini tentang komentar di Markdown). Ini masih membuat area Halaman Terkait, dengan placeholder (kosong). Itu mengganggu, tapi setidaknya saya mendapat halaman utama
Evgen
55

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.

doxygen
sumber
6
Sebenarnya penurunan harga dukungan versi 1.8.0 TAPI tidak memperlakukan mereka sebagai dokumentasi. Jadi Anda akan berakhir dengan kelas penurunan harga yang tercantum di bagian File dan Direktori. Solusi adalah dengan menambahkan dox=mdsebagai EXTENSION_MAPPINGdan mengubah nama ekstensi penurunan harga untuk .doxJadi config akan terlihat seperti:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
bersifat antitoksin
6
Poin yang bagus. Saya akan memperbaiki ini sehingga .md dan .markdown diperlakukan mirip dengan .dox.
doxygen
4
Sayangnya, ini berakhir di Halaman Terkait, bukan sebagai halaman utama
Evgen
7

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

Birol Capa
sumber
@FelixSFD terima kasih atas tanggapan Anda. Saya memperbarui jawaban saya sesuai dengan jawaban Anda.
Birol Capa
3

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.

VorpalSword
sumber
1
klarifikasi - doxywizard adalah ujung depan GUI yang diinstal di macOS.
VorpalSword
Saya harus menambahkan \ mainpage agar README.md dikenali sebagai halaman utama
JBaczuk