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?
102
Respostas:
Dê uma olhada no
mainpage
comando.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
,.txt
e.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.dox
arquivo (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 ++.fonte
.md
e.markdown
) são considerados também como arquivos de documentação adicional. Eu os prefiro.dox
porque eles não precisam de comentários de código ao redor e podem ser bem editados com um editor de markdown - sem inconvenientes.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 ,INPUT
e defini-lo como o valor desta opção:fonte
USE_MDFILE_AS_MAINPAGE
nã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.INPUT = README.md
thenINPUT += src
(para seguir a sugestão de @Lester) e oUSE_MDFILE_AS_MAINPAGE = README.md
e funcionou perfeitamente. Versão:$ doxygen --version
retorna1.8.11
para mim.\mainpage
dentro (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 principalObserve 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
.md
ou.markdown
e adicionar o seguinte ao arquivo de configuração:Consulte http://www.doxygen.nl/manual/markdown.html#md_page_header para obter detalhes.
fonte
dox=md
comoEXTENSION_MAPPING
e renomear suas extensões de markdown para.dox
. Portanto, a configuração será semelhante a:INPUT += your_page.dox EXTENSION_MAPPING += dox=md
A sintaxe a seguir pode ajudar a adicionar uma página principal e subpáginas relacionadas para doxygen:
A criação de grupos da seguinte forma também ajuda na criação de páginas:
Um exemplo pode ser encontrado aqui
fonte
Adicione qualquer arquivo na documentação que incluirá seu conteúdo, por exemplo toc.h :
E em seu
Doxyfile
: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)
fonte
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_MAINPAGE
configuração.Ele fez as seguintes alterações em meu Doxyfile:
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.fonte