I made documentation for my SDK, using Doxygen. It contains the list of files, namespaces, classes, types etc. - everything that I placed as Doxygen comments in the code. Now I want to write some general information about SDK (kind of introduction), which is not related directly to any code element. I want to place this introduction on the documentation start page. How can I do this?
This question is related to
doxygen
Have a look at the mainpage command.
Also, have a look this answer to another thread: How to include custom files in Doxygen. It states that there are three extensions which doxygen classes as additional documentation files: .dox, .txt and .doc. Files with these extensions do not appear in the file index but can be used to include additional information into your final documentation - very useful for documentation that is necessary but that is not really appropriate to include with your source code (for example, an FAQ)
So I would recommend having a mainpage.dox (or similarly named) file in your project directory to introduce you SDK. Note that inside this file you need to put one or more C/C++ style comment blocks.
Add any file in the documentation which will include 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):
Following syntax may help for adding a main page and related 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 groups as following also help for designing pages:
/** \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.
*/
Note that with Doxygen release 1.8.0 you can also add Markdown formated pages. For this to work you need to create pages with a .md or .markdown extension, and add the following to the config file:
INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown
See http://www.doxygen.nl/manual/markdown.html#md_page_header for details.
I tried all the above with v 1.8.13 to no avail.
What worked for me (on macOS) was to use the doxywizard->Expert tag to fill the USE_MD_FILE_AS_MAINPAGE setting.
It made the following changes to my Doxyfile:
USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT = ../README.md \
../sdk/include \
../sdk/src
Note the line termination for INPUT, I had just been using space as a separator as specified in the documentation. AFAICT this is the only change between the not-working and working version of the Doxyfile.
As of v1.8.8 there is also the option USE_MDFILE_AS_MAINPAGE. So make sure to add your index file, e.g. README.md, to INPUT and set it as this option's value:
INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Source: Stackoverflow.com