Cách tạo trang giới thiệu với Doxygen

Tôi đã tạo tài liệu cho SDK của mình bằng Doxygen. Nó chứa danh sách các tệp, không gian tên, lớp, loại, v.v. - mọi thứ mà tôi đã đặt dưới dạng nhận xét Doxygen trong mã. Bây giờ tôi muốn viết một số thông tin chung về SDK (dạng giới thiệu), không liên quan trực tiếp đến bất kỳ phần tử mã nào. Tôi muốn đặt phần giới thiệu này trên trang bắt đầu của tài liệu. Tôi có thể làm cái này như thế nào?

Hãy xem mainpagelệnh.

Ngoài ra, hãy xem câu trả lời này cho một chủ đề khác: Cách bao gồm các tệp tùy chỉnh trong Doxygen . Nó nói rằng có ba phần mở rộng mà Doxygen lớp như các file tài liệu bổ sung: .dox, .txtvà .doc. Các tệp có các phần mở rộng này không xuất hiện trong chỉ mục tệp nhưng có thể được sử dụng để bao gồm thông tin bổ sung vào tài liệu cuối cùng của bạn - rất hữu ích cho tài liệu cần thiết nhưng điều đó không thực sự thích hợp để đưa vào mã nguồn của bạn (ví dụ: Câu hỏi thường gặp)

Vì vậy, tôi khuyên bạn nên có một mainpage.doxtệp (hoặc có tên tương tự) trong thư mục dự án của bạn để giới thiệu SDK cho bạn. Lưu ý rằng bên trong tệp này, bạn cần đặt một hoặc nhiều khối chú thích kiểu C / C ++.

Kể từ v1.8.8 cũng có tùy chọn USE_MDFILE_AS_MAINPAGE. Vì vậy, hãy đảm bảo thêm tệp chỉ mục của bạn, ví dụ: README.md , vào INPUTvà đặt nó làm giá trị của tùy chọn này:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Lưu ý rằng với bản phát hành Doxygen 1.8.0, bạn cũng có thể thêm các trang được định dạng Markdown. Để điều này hoạt động, bạn cần tạo các trang có phần mở rộng .mdhoặc .markdownđuôi và thêm phần sau vào tệp cấu hình:

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

Xem http://www.doxygen.nl/manual/markdown.html#md_page_header để biết chi tiết.

Cú pháp sau có thể giúp thêm một trang chính và các trang con liên quan cho 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"
 */

Tạo các nhóm như sau cũng giúp thiết kế các trang:

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

Một ví dụ có thể được tìm thấy ở đây

Thêm bất kỳ tệp nào trong tài liệu sẽ bao gồm nội dung của bạn, ví dụ toc.h :

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

Và trong Doxyfile:

INPUT = toc.h \

Ví dụ (bằng tiếng Nga):

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

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

Tôi đã thử tất cả những điều trên với v 1.8.13 nhưng không có kết quả. Điều phù hợp với tôi (trên macOS) là sử dụng thẻ doxywizard-> Expert để điền vào USE_MD_FILE_AS_MAINPAGEcài đặt.

Nó đã thực hiện các thay đổi sau đối với Doxyfile của tôi:

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

Lưu ý kết thúc dòng cho INPUT, tôi vừa mới sử dụng khoảng trắng làm dấu phân cách như được chỉ định trong tài liệu. AFAICT, đây là thay đổi duy nhất giữa phiên bản không hoạt động và hoạt động của Doxyfile.