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

102

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?

Alex F
fonte

Respostas:

95

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 ++.

Chris
fonte
3
Pelo menos os arquivos markdown ( .mde .markdown) são considerados também como arquivos de documentação adicional. Eu os prefiro .doxporque eles não precisam de comentários de código ao redor e podem ser bem editados com um editor de markdown - sem inconvenientes.
Pascal
56

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
Pascal
fonte
4
Além disso, se você for usar README.md como a página principal, certifique-se de que ele seja o primeiro na lista INPUT. Quando há vários candidatos à página principal, o primeiro encontrado durante a análise é selecionado ou assim parece.
Lester Peabody,
2
A propósito, no doxygen gui, você só precisa incluir seu arquivo .md em expert> input> input.
Adrian Lopez
USE_MDFILE_AS_MAINPAGEnão funcionou para mim. De acordo com a documentação, você deve incluir {#mainpage}após o título do documento de remarcação. Isso funcionou.
samvv
2
@samvv Não adicionei nenhum extra ao documento de redução de preço. Só usei o INPUT = README.mdthen INPUT += src(para seguir a sugestão de @Lester) e o USE_MDFILE_AS_MAINPAGE = README.mde funcionou perfeitamente. Versão: $ doxygen --versionretorna 1.8.11para mim.
Xavi Montero
1
No Doxygen 1.8.2, a única coisa que funcionou foi adicionar \mainpagedentro (pode fazer isso em um comentário (veja este link sobre comentários no MarkDown). Isso ainda criou a área de páginas relacionadas, com um espaço reservado (vazio). Isso é irritante, mas pelo menos eu tenho a página principal
Evgen
55

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.

doxygen
fonte
6
Na verdade, a versão atual 1.8.0 suporta markdown, MAS não os trata como documentação. Portanto, você acabará com classes de redução listadas na seção Arquivos e diretórios. A solução é adicionar dox=mdcomo EXTENSION_MAPPINGe renomear suas extensões de markdown para .dox. Portanto, a configuração será semelhante a:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
antitóxico
6
Bom ponto. Vou corrigir isso de forma que .md e .markdown sejam tratados de forma semelhante a .dox.
doxygen
4
Infelizmente, isso acaba nas páginas relacionadas, não como a página principal
Evgen
7

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

Birol Capa
fonte
@FelixSFD obrigado por seu feedback. Eu atualizei minha resposta de acordo com sua resposta.
Birol Capa
3

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.

VorpalSword
fonte
1
esclarecimento - doxywizard é o front-end da GUI que pode ser instalado no macOS.
VorpalSword
Tive que adicionar \ mainpage para que README.md fosse reconhecido como a página principal
JBaczuk