Como fazer uma página de introdução com Doxygen

Fiz documentação para meu SDK, usando Doxygen. Ele contém a lista de arquivos, namespaces, classes, tipos, etc. - tudo que coloquei como comentários do Doxygen no código. Agora, quero escrever algumas informações gerais sobre o SDK (espécie de introdução), que não estão diretamente relacionadas a nenhum elemento de código. Quero colocar esta introdução na página inicial da documentação. Como posso fazer isso?

Dê uma olhada no mainpagecomando.

Além disso, dê uma olhada nesta resposta em outro tópico: Como incluir arquivos personalizados no Doxygen . Ele afirma que existem três extensões que Doxygen aulas como arquivos de documentação adicionais: .dox, .txte .doc. Os arquivos com essas extensões não aparecem no índice de arquivos, mas podem ser usados ​​para incluir informações adicionais em sua documentação final - muito útil para a documentação necessária, mas que não é realmente apropriada para incluir em seu código-fonte (por exemplo, um FAQ)

Portanto, eu recomendaria ter um mainpage.doxarquivo (ou um nome semelhante) no diretório do projeto para apresentar o SDK. Observe que dentro desse arquivo você precisa colocar um ou mais blocos de comentários no estilo C / C ++.

A partir da v1.8.8 também existe a opção USE_MDFILE_AS_MAINPAGE. Portanto, certifique-se de adicionar seu arquivo de índice, por exemplo , README.md , INPUTe defini-lo como o valor desta opção:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Observe que com a versão 1.8.0 do Doxygen, você também pode adicionar páginas formatadas em Markdown. Para que isso funcione, você precisa criar páginas com uma extensão .mdou .markdowne adicionar o seguinte ao arquivo de configuração:

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

Consulte http://www.doxygen.nl/manual/markdown.html#md_page_header para obter detalhes.

A sintaxe a seguir pode ajudar a adicionar uma página principal e subpáginas relacionadas para 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"
 */

A criação de grupos da seguinte forma também ajuda na criação de páginas:

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

Um exemplo pode ser encontrado aqui

Adicione qualquer arquivo na documentação que incluirá seu conteúdo, por exemplo toc.h :

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

E em seu Doxyfile:

INPUT = toc.h \

Exemplo (em russo):

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

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

Tentei todos os itens acima com a v 1.8.13 sem sucesso. O que funcionou para mim (no macOS) foi usar a tag doxywizard-> Expert para preencher a USE_MD_FILE_AS_MAINPAGEconfiguração.

Ele fez as seguintes alterações em meu Doxyfile:

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

Observe a terminação de linha para INPUT, eu acabava de usar o espaço como separador, conforme especificado na documentação. AFAICT, esta é a única alteração entre a versão não funcional e a versão funcional do Doxyfile.