Merge pull request mavlink#374 from hamishwillee/fix_notes

Add better support for note/warning types and update docs appopriately

core/dronecore.h

@@ -54,7 +54,7 @@ class DroneCore
      * Default URL : udp://:14540.
      * - Default Bind host IP is localhost(127.0.0.1)
      *
-     * Warning: serial connections are not supported on Windows (they are supported on Linux and macOS).
+     * @warning Serial connections are not supported on Windows (they are supported on Linux and macOS).
      *
      * @param connection_url connection URL string.
      * @return The result of adding the connection.
@@ -83,7 +83,7 @@ class DroneCore
      * @brief Adds a serial connection with a specific port (COM or UART dev node) and baudrate as specified.
      *
      *
-     * Warning: this method is not supported on Windows (it is supported on Linux and macOS).
+     * @warning This method is not supported on Windows (it is supported on Linux and macOS).
      *
      * @param dev_path COM or UART dev node name/path (defaults to "/dev/ttyS0").
      * @param baudrate Baudrate of the serial port (defaults to 57600).
@@ -160,7 +160,7 @@ class DroneCore
      * If systems have been discovered before this callback is registered, they will be notified
      * at the time this callback is registered.
      *
-     * **Note** Only one callback can be registered at a time. If this function is called several
+     * @note Only one callback can be registered at a time. If this function is called several
      * times, previous callbacks will be overwritten.
      *
      * @param callback Callback to register.
@@ -174,7 +174,7 @@ class DroneCore
      * This sets a callback that will be notified if no heartbeat of the system has been received
      * in 3 seconds.
      *
-     * **Note** Only one callback can be registered at a time. If this function is called several
+     * @note Only one callback can be registered at a time. If this function is called several
      * times, previous callbacks will be overwritten.
      *
      * @param callback Callback to register.

generate_markdown_from_doxygen_xml.py

@@ -96,9 +96,9 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False):
             if child.attrib['kind']=='return':
                 pass # simplesect contains return info for function. We parse it specifically in other code so here we make sure it this tag doesn't get processed.
             elif child.attrib['kind']=='see':
-                pass #Prevent further handling of "see" children.  
-            elif child.attrib['kind']=='note':
-                pass #Prevent further handling of "note" children.  
+                pass #Prevent further handling of "see" children.
+            elif child.attrib['kind']=='warning' or child.attrib['kind']=='note' or child.attrib['kind']=='since' or child.attrib['kind']=='attention' or child.attrib['kind']=='remark': #Pass 'note' types to specific handling
+                child_text += markdown_any_tag(child,html=html,para=para) #.strip() //Handle warnings individually
             else:
                 #Just in case there is a different type of simplesect, this tells us we need to think about it.
                 print('Unhanded kind in simplesect tag in markdown_any_tag:kind: %s' % child.attrib['kind'])
@@ -158,7 +158,7 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False):
             tag_text=lead_text+child_text+tail_text
     elif aTag.tag=='itemizedlist':
         if html:
-            tag_text='\n<ul>'+lead_text+child_text+'</ul>'+tail_text
+            tag_text='\n<ul>\n'+lead_text.strip()+child_text.strip()+'\n</ul>'+tail_text
         else:
             tag_text='\n'+lead_text+child_text+tail_text+'\n' #single level implementation.
     elif aTag.tag=='listitem':
@@ -200,39 +200,31 @@ def markdown_any_tag(aTag, html=False,para=True,consume=False):
         tag_text=lead_text+tail_text #note, child text included in the URL text above. There won't be any though.
         #print('tag_text: %s' % tag_text)
 
-    elif aTag.tag=='detaileddescription':
-        #Strip out note tags from detailed description (so it can be agreggated under Notes section)
-        note_tags=aTag.findall(".//simplesect[@kind='note']")
-        note_text=''
-        if note_tags:
-            for item in note_tags:
-                note_text+='\n%s' % markdown_any_tag(item).strip()
-
-            note_text='\n\n**Notes:**\n\n%s\n\n' % note_text
-            #print('debug:tag:note_text: %s' % note_text)
-
-        #Strip out seealso tags from detailed description (so it can be agreggated under Seealso section)
-        """
-        seealso_tags=aTag.findall(".//simplesect[@kind='see']")
-        seealso_text=''
-        if seealso_tags:
-            for item in seealso_tags:
-                seealso_text+='\n- %s' % markdown_any_tag(item).strip()
-
-            seealso_text='\n\n**See Also:**%s\n\n' % seealso_text
-            #print('debug:tag:seealso_text: %s' % seealso_text)
-        """
 
-        tag_text=lead_text+child_text+note_text+tail_text
+    elif aTag.tag=='detaileddescription':
+        tag_text=lead_text+child_text+tail_text
 
 
     elif aTag.tag=='simplesect':
-        if aTag.attrib['kind']=='note' or aTag.attrib['kind']=='see' or aTag.attrib['kind']=='return':
+        if aTag.attrib['kind']=='see' or aTag.attrib['kind']=='return':
             #Handle @note (note) and @sa (see) tags.
             # Note we should ONLY see this via the detaileddescription handling 
             # Because children that are simplesect are not parsed.
             tag_text=lead_text+child_text+tail_text
 
+        #Convert "note" types     
+        if aTag.attrib['kind']=='warning' or aTag.attrib['kind']=='note' or aTag.attrib['kind']=='attention':
+            #print('Debug: kind %s' % aTag.attrib['kind'])  
+            noteTypeText=aTag.attrib['kind'].capitalize()            
+            if para:
+                 if html:
+                     tag_text='<p>'+lead_text+'<b>'+noteTypeText+': </b> '+child_text+'</p>'+tail_text
+                 else: # ONLY THIS PATH TESTED (others should not occur, but leaving in as standard.
+                     tag_text='\n\n> **'+noteTypeText+'** '+lead_text.strip()+child_text.strip()+'\n\n'+tail_text.strip()
+            else: #para disabled, render without them.
+                tag_text='\n\n> **'+noteTypeText+'** '+ lead_text.strip()+child_text.strip()+tail_text.strip()        
+
+
     elif aTag.tag=='verbatim':
         tag_text='\n\n'+lead_text+child_text+'\n\n'+tail_text
 

plugins/action/action.h

@@ -47,7 +47,7 @@ class Action : public PluginBase
     /**
      * @brief Send command to *arm* the drone (synchronous).
      *
-     * **Note** Arming a drone normally causes motors to spin at idle.
+     * @note Arming a drone normally causes motors to spin at idle.
      * Before arming take all safety precautions and stand clear of the drone!
      *
      * @return ActionResult of request.

plugins/action/action_result.h

@@ -8,7 +8,7 @@ namespace dronecore {
 /**
  * @brief Possible results returned for commanded actions.
  *
- * **Note**: DroneCore does not throw exceptions. Instead a result of this type will be
+ * @note DroneCore does not throw exceptions. Instead a result of this type will be
  * returned when you execute actions.
  */
 enum class ActionResult {