issue #6925 Missing ATX headings in markdown pages

In general ATX headers ('#' headers and other markdown ) are converted to doxygen `\section` etc. commands
In case not all levels of doxygen commands are present so like;
```
\section  sect1 Section
....
\subsubsection subsubsect1 Sub sub section

```
the information of the `\subsubsection` is not shown. Same happens in case the `\section` is not present at all.
Part of the steering of the ATX headers is done by means of the configuration setting TOC_INCLUDE_HEADINGS (default is 5) setting this setting to '0' will not convert the '#' headers to `\section` etc. (but this as side note).

Basic problem is fixing the not shown headers in case of missing levels in the `\section` commands.
- In case the `\section` command does start the page
- In case the `\section` command does not start the page.

Case the `\section` command does start the page: this is handled in the routine `int DocSection::parse()`
- see to it that not only the exact matching level is handled but also the 'jumps' in levels
- loop all 'section' of the found type and its sub sections and only jump out in case of the 'jump' level case
- give a warning in case of a 'level jump'

Case the `\section` command does not start the page: this is handled in the routine ` void DocRoot::parse()`
- as e.g. `\paragraph` could be followed by a `\subsubsection` each section type has to be handled one after another (otherwise higher types would not be handled)
- note the order is important therefore a `\subsubsection` has to be handled after a `\paragraph.
- due to the different handling the 'TK_LISTITEM' has to be handled at the end (each part can also give a 'TK_LISTITEM'

1 files changed, 101 insertions, 49 deletions

diff --git a/src/docparser.cpp b/src/docparser.cpp
index 90ace3f..991080d 100644
--- a/src/docparser.cpp
+++ b/src/docparser.cpp
@@ -6885,54 +6885,55 @@ int DocSection::parse()
 
   //printf("m_level=%d <-> %d\n",m_level,Doxygen::subpageNestingLevel);
 
-  if (retval==RetVal_Subsection && m_level==Doxygen::subpageNestingLevel+1)
+  while (true)
   {
-    // then parse any number of nested sections
-    while (retval==RetVal_Subsection) // more sections follow
+    if (retval==RetVal_Subsection && m_level<=Doxygen::subpageNestingLevel+1)
     {
-      //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
-      DocSection *s=new DocSection(this,
-          QMIN(2+Doxygen::subpageNestingLevel,5),g_token->sectionId);
-      m_children.append(s);
-      retval = s->parse();
+      // then parse any number of nested sections
+      while (retval==RetVal_Subsection) // more sections follow
+      {
+        //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
+        DocSection *s=new DocSection(this,
+            QMIN(2+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+        m_children.append(s);
+        retval = s->parse();
+      }
+      break;
     }
-  }
-  else if (retval==RetVal_Subsubsection && m_level==Doxygen::subpageNestingLevel+2)
-  {
-    // then parse any number of nested sections
-    while (retval==RetVal_Subsubsection) // more sections follow
+    else if (retval==RetVal_Subsubsection && m_level<=Doxygen::subpageNestingLevel+2)
     {
-      //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
-      DocSection *s=new DocSection(this,
-          QMIN(3+Doxygen::subpageNestingLevel,5),g_token->sectionId);
-      m_children.append(s);
-      retval = s->parse();
+      if ((m_level<=1+Doxygen::subpageNestingLevel) && !QString(g_token->sectionId).startsWith("autotoc_md"))
+          warn_doc_error(g_fileName,doctokenizerYYlineno,"Unexpected subsubsection command found inside %s!",sectionLevelToName[m_level]);
+      // then parse any number of nested sections
+      while (retval==RetVal_Subsubsection) // more sections follow
+      {
+        //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
+        DocSection *s=new DocSection(this,
+            QMIN(3+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+        m_children.append(s);
+        retval = s->parse();
+      }
+      if (!(m_level<Doxygen::subpageNestingLevel+2 && retval == RetVal_Subsection)) break;
     }
-  }
-  else if (retval==RetVal_Paragraph && m_level==QMIN(5,Doxygen::subpageNestingLevel+3))
-  {
-    // then parse any number of nested sections
-    while (retval==RetVal_Paragraph) // more sections follow
+    else if (retval==RetVal_Paragraph && m_level<=QMIN(5,Doxygen::subpageNestingLevel+3))
     {
-      //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
-      DocSection *s=new DocSection(this,
-          QMIN(4+Doxygen::subpageNestingLevel,5),g_token->sectionId);
-      m_children.append(s);
-      retval = s->parse();
+      if ((m_level<=2+Doxygen::subpageNestingLevel) && !QString(g_token->sectionId).startsWith("autotoc_md"))
+        warn_doc_error(g_fileName,doctokenizerYYlineno,"Unexpected paragraph command found inside %s!",sectionLevelToName[m_level]);
+      // then parse any number of nested sections
+      while (retval==RetVal_Paragraph) // more sections follow
+      {
+        //SectionInfo *sec=Doxygen::sectionDict[g_token->sectionId];
+        DocSection *s=new DocSection(this,
+            QMIN(4+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+        m_children.append(s);
+        retval = s->parse();
+      }
+      if (!(m_level<Doxygen::subpageNestingLevel+3 && (retval == RetVal_Subsection || retval == RetVal_Subsubsection))) break; 
+    }
+    else
+    {
+      break;
     }
-  }
-  else if ((m_level<=1+Doxygen::subpageNestingLevel && retval==RetVal_Subsubsection) ||
-           (m_level<=2+Doxygen::subpageNestingLevel && retval==RetVal_Paragraph)
-          )
-  {
-    int level = (retval==RetVal_Subsubsection) ? 3 : 4;
-    warn_doc_error(g_fileName,doctokenizerYYlineno,"Unexpected %s "
-            "command found inside %s!",
-            sectionLevelToName[level],sectionLevelToName[m_level]);
-    retval=0; // stop parsing
-  }
-  else
-  {
   }
 
   INTERNAL_ASSERT(retval==0 || 
@@ -7086,21 +7087,72 @@ void DocRoot::parse()
     {
       delete par;
     }
-    if (retval==TK_LISTITEM)
+    if (retval==RetVal_Paragraph)
     {
-      warn_doc_error(g_fileName,doctokenizerYYlineno,"Invalid list item found");
+      if (!QString(g_token->sectionId).startsWith("autotoc_md"))
+         warn_doc_error(g_fileName,doctokenizerYYlineno,"found paragraph command outside of subsubsection context!");
+      while (retval==RetVal_Paragraph)
+      {
+        SectionInfo *sec=Doxygen::sectionDict->find(g_token->sectionId);
+        if (sec)
+        {
+          DocSection *s=new DocSection(this,
+              QMIN(4+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+          m_children.append(s);
+          retval = s->parse();
+        }
+        else
+        {
+          warn_doc_error(g_fileName,doctokenizerYYlineno,"Invalid paragraph id `%s'; ignoring paragraph",qPrint(g_token->sectionId));
+          retval = 0;
+        }
+      }
     }
-    else if (retval==RetVal_Subsection)
+    if (retval==RetVal_Subsubsection)
     {
-      warn_doc_error(g_fileName,doctokenizerYYlineno,"found subsection command outside of section context!");
+      if (!(QString(g_token->sectionId).startsWith("autotoc_md")))
+        warn_doc_error(g_fileName,doctokenizerYYlineno,"found subsubsection command outside of subsection context!");
+      while (retval==RetVal_Subsubsection)
+      {
+        SectionInfo *sec=Doxygen::sectionDict->find(g_token->sectionId);
+        if (sec)
+        {
+          DocSection *s=new DocSection(this,
+              QMIN(3+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+          m_children.append(s);
+          retval = s->parse();
+        }
+        else
+        {
+          warn_doc_error(g_fileName,doctokenizerYYlineno,"Invalid subsubsection id `%s'; ignoring subsubsection",qPrint(g_token->sectionId));
+          retval = 0;
+        }
+      }
     }
-    else if (retval==RetVal_Subsubsection)
+    if (retval==RetVal_Subsection)
     {
-      warn_doc_error(g_fileName,doctokenizerYYlineno,"found subsubsection command outside of subsection context!");
+      if (!(QString(g_token->sectionId).startsWith("autotoc_md")))
+        warn_doc_error(g_fileName,doctokenizerYYlineno,"found subsection command outside of section context!");
+      while (retval==RetVal_Subsection)
+      {
+        SectionInfo *sec=Doxygen::sectionDict->find(g_token->sectionId);
+        if (sec)
+        {
+          DocSection *s=new DocSection(this,
+              QMIN(2+Doxygen::subpageNestingLevel,5),g_token->sectionId);
+          m_children.append(s);
+          retval = s->parse();
+        }
+        else
+        {
+          warn_doc_error(g_fileName,doctokenizerYYlineno,"Invalid subsection id `%s'; ignoring subsection",qPrint(g_token->sectionId));
+          retval = 0;
+        }
+      }
     }
-    else if (retval==RetVal_Paragraph)
+    if (retval==TK_LISTITEM)
     {
-      warn_doc_error(g_fileName,doctokenizerYYlineno,"found paragraph command outside of subsubsection context!");
+      warn_doc_error(g_fileName,doctokenizerYYlineno,"Invalid list item found");
     }
     if (retval==RetVal_Internal)
     {