วิธีสร้างหน้าแนะนำด้วย Doxygen

ฉันทำเอกสารสำหรับ SDK ของฉันโดยใช้ Doxygen มันมีรายการไฟล์เนมสเปซคลาสประเภท ฯลฯ - ทุกอย่างที่ฉันวางไว้เป็นความคิดเห็นของ Doxygen ในโค้ด ตอนนี้ฉันต้องการเขียนข้อมูลทั่วไปเกี่ยวกับ SDK (ชนิดของบทนำ) ซึ่งไม่เกี่ยวข้องโดยตรงกับองค์ประกอบโค้ดใด ๆ ฉันต้องการวางบทนำนี้ในหน้าเริ่มต้นของเอกสาร ฉันจะทำเช่นนี้ได้อย่างไร?

ดูmainpageคำสั่ง

นอกจากนี้มีลักษณะเป็นคำตอบนี้ไปยังหัวข้ออื่น: วิธีการรวมไฟล์ที่กำหนดเองใน Doxygen มันระบุว่ามีสามส่วนขยายที่ Doxygen เรียนเป็นไฟล์เอกสารเพิ่มเติม: .dox, และ.txt .docไฟล์ที่มีนามสกุลเหล่านี้จะไม่ปรากฏในดัชนีไฟล์ แต่สามารถใช้เพื่อรวมข้อมูลเพิ่มเติมลงในเอกสารขั้นสุดท้ายของคุณซึ่งมีประโยชน์มากสำหรับเอกสารประกอบที่จำเป็น แต่ไม่เหมาะสมที่จะรวมไว้ในซอร์สโค้ดของคุณ (เช่นคำถามที่พบบ่อย)

ดังนั้นฉันขอแนะนำให้มีไฟล์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ส่วนขยายและเพิ่มสิ่งต่อไปนี้ในไฟล์ config:

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

ดูรายละเอียดได้ที่http://www.doxygen.nl/manual/markdown.html#md_page_header

ไวยากรณ์ต่อไปนี้อาจช่วยในการเพิ่มหน้าหลักและหน้าย่อยที่เกี่ยวข้องสำหรับ 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 \

ตัวอย่าง (ในรัสเซีย):

• 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-> แท็กผู้เชี่ยวชาญเพื่อเติมเต็มการUSE_MD_FILE_AS_MAINPAGEตั้งค่า

ได้ทำการเปลี่ยนแปลงต่อไปนี้กับ Doxyfile ของฉัน:

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

สังเกตการสิ้นสุดบรรทัดสำหรับINPUTฉันเพิ่งใช้ช่องว่างเป็นตัวคั่นตามที่ระบุไว้ในเอกสารประกอบ AFAICT นี่เป็นการเปลี่ยนแปลงเพียงอย่างเดียวระหว่าง Doxyfile เวอร์ชันที่ใช้งานไม่ได้และใช้งานได้