How to make an introduction page with Doxygen

Question

I made documentation for my SDK using Doxygen. It contains a list of files, namespaces, classes, types, etc. - everything that I put as Doxygen code in the code. Now I want to write some general information about the SDK (type of introduction), which is not directly related to any element of the code. I want to place this introduction on the start page of the documentation. How can i do this?

Answer 1

Take a look at the mainpage command.

Also see this answer in another thread: How to include user files in Doxygen . It says that there are three extensions that make .dox classes as additional documentation files: .dox , .txt and .doc . Files with these extensions are not displayed in the file index, but they can be used to include additional information in the final documentation. This is very useful for documentation, which is necessary, but not entirely suitable for inclusion in the source code (for example, FAQ)

Therefore, I would recommend having a mainpage.dox file (or with a similar name) in your project directory to present you with an SDK. Note that inside this file you need to place one or more comment blocks in C / C ++ style.

Answer 2

Please note that in Doxygen version 1.8.0 you can also add formatted Markdown pages. For this to work, you need to create pages with the extension .md or .markdown and add the following to the configuration file:

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

See http://www.doxygen.nl/manual/markdown.html#md_page_header for details.

Answer 3

As in version 1.8.8, there is the USE_MDFILE_AS_MAINPAGE option. Therefore, be sure to add an index file, for example. README.md, before INPUT and set it as the value of this parameter:

 INPUT += README.md USE_MDFILE_AS_MAINPAGE = README.md 

Answer 4

Add any file to the documentation that will contain your content, for example toc.h :

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

And in your Doxyfile :

 INPUT = toc.h \ 

Example (in Russian):

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

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

Answer 5

The following syntax can help add the main page and its associated subpages for 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" */ 

Creating the following groups also helps with page design:

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

An example can be found here.

Answer 6

I tried everything above with v 1.8.13 to no avail. For me (on macOS), use the doxywizard-> Expert tag to populate the USE_MD_FILE_AS_MAINPAGE parameter.

He made the following changes to my Doxyfile:

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

Note the line ending for INPUT , I just used a space as a delimiter, as indicated in the documentation. AFAICT is the only change between a non-working and working version of Doxyfile.