l'étiquette d'en-tête dans la page markdown de doxygen fait disparaître le titre de l'en-tête

Question

J'ai remarqué un étrange problème avec doxygen 1.8.2. L'inclusion d'une étiquette d'en-tête fait disparaître le titre de l'en-tête de la sortie html.

Avec le fichier markdown suivant :

Title            {#title}
=====

Section 1        {#section1}
---------
Text for section 1

J'obtiens le résultat suivant :

Titre

Texte pour la section 1

Mais, si je retire le {#section1} à partir du fichier markdown, j'obtiens la sortie correcte suivante :

Titre

Section 1

Texte pour la section 1

Quelle est l'erreur que je fais ici ?

Modifier J'ai observé l'avertissement suivant lorsque j'étiquette une section :

 warning: found subsection command outside of section context!

Answer 1

Après quelques recherches, j'ai décidé que apparaît pour être un bogue, mais seulement parce qu'il est légèrement contre-intuitif.

Considérez ce qui suit :

The Main Section {#the_main_section}
================

Subsection One {#first}
--------------

Something highly interesting...

Le document commence par un en-tête de niveau 1 (comme décrit dans la section aquí ) et donc Doxygen interprète "La section principale" comme le nom et le titre de la page. L'en-tête et l'étiquette {#the_main_section} semblent ne pas être pris en compte une fois que l'en-tête a été converti en nom de page.

Le traitement passe ensuite au reste du document et lorsqu'il atteint la "sous-section un", il pense qu'il n'y a pas de "section" parente pour la "sous-section" (car la "section" a été convertie en nom de page) et c'est là qu'il s'arrête.

Plus précisément, il élimine la sous-section (en-tête) car il estime qu'il n'y a pas de "section" parente. Tout le reste du texte est conservé, mais est traité comme faisant partie de la "page" (sans section parente).

Le "correctif" consiste à ajouter un autre "en-tête de niveau 1" après l'en-tête de niveau 1 initial.

My Great Documentation (Which Becomes the Page Name)
====================================================

The First Section
=================

Q. What? I already created a level 1 heading?
A. Yup, but that was converted to a page name/title and discarded, so now
   we have to create another level 1 heading for my first section. Don't
   be fooled into thinking that the opening heading in this document is
   still treated as an opening heading by Doxygen - it's not!

Answer 2

Même problème dans la version 1.8.9.1. Vous pouvez l'éviter en utilisant les balises # au lieu de --- .

Par exemple :

[TOC]

Page Title {#pageTitle}
==========
Lorem ipsum dolor sit amet

# section 1 {#section1}
Lorem ipsum dolor sit amet

## Section 1.1 {#section1-1}
Lorem ipsum dolor sit amet

# section 2 {#section2}
Lorem ipsum dolor sit amet

# section 3 {#section3}
Lorem ipsum dolor sit amet

## section 3.1 {#section3-1}
Lorem ipsum dolor sit amet

# section 4 {#section4}
Lorem ipsum dolor sit amet

fonctionnera. Vous pouvez même placer la balise [TOC] sous la définition du titre de la page pour la supprimer de la table des matières.

Answer 3

J'utilise Doxygen 1.8.14 et j'ai eu le même problème. Je veux partager comment je l'ai résolu.

Comme suggéré dans http://svenax.net/site/2013/07/creating-user-documentation-with-doxygen/ J'ai défini USE_MDFILE_AS_MAINPAGE = mainpage.md, et je me suis également assuré d'étiqueter toutes les sections et sous-sections.

Comme mentionné par Lester Burnham, le document a besoin de deux en-têtes de niveau 1. Cependant, pour que cela fonctionne, il faut utiliser le style "=========" pour le premier et le style "#" pour le second. Comme ceci :

My main page    {#mainpage}
============

# Introduction  {#intro}
Text.....

## A sub section    {#subsection1}
Text... and a reference to the [Introduction](#intro).

Avec cela, ma page principale de Doxygen fonctionne bien. Tous les en-têtes apparaissent et les références fonctionnent. J'espère que cela vous aidera ! =)

Answer 4

J'avais des difficultés à contrôler le titre de mes pages Markdown dans Doxygen ; j'ai fini par utiliser la commande @page de Doxygen :

@page pageLabel Ceci est le titre de ma page

Cela me permet de faire référence à la page en utilisant @ref pageLabel, et dans ma section Pages, elle apparaît comme "Ceci est le titre de ma page".

Cela m'a été particulièrement utile car je veux que mes titres comportent des espaces, ce qui n'est pas possible si Doxygen utilise le nom du fichier comme titre.