Docs generation improvements (mavlink#2139)

* Dialects more clearly not necessarily accurate to fork

* Common.xml includes all entities

Author: hamishwillee

doc/mavlink_xml_to_markdown.py

@@ -297,16 +297,6 @@ def get_top_level_docs(self, filename):
 The original definitions are defined in [standard.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/standard.xml).
     """
 
-        elif filename == 'ardupilotmega':
-            insert_text += """
-# Dialect: ArduPilotMega
-
-These messages define the ArduPilot specific message set, which is custom to [http://ardupilot.org](http://ardupilot.org).
-
-This topic is a human-readable form of the XML definition file: [ardupilotmega.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/ardupilotmega.xml).
-
-> **Warning** The ArduPilot MAVLink fork of [ardupilotmega.xml](https://github.com/ArduPilot/mavlink/blob/master/message_definitions/v1.0/ardupilotmega.xml) may contain messages that have not yet been merged into this documentation.
-    """
         elif filename == 'development':
             insert_text += """
 # Dialect: development
@@ -315,28 +305,75 @@ def get_top_level_docs(self, filename):
 They should be considered a 'work in progress' and not included in production builds.
 
 This topic is a human-readable form of the XML definition file: [development.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/development.xml).
+"""
+        elif filename == 'test':
+            insert_text += """
+# Dialect: test
+
+The test dialect is used for testing XML file parsing.
+
+This topic is a human-readable form of the XML definition file: [test.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/test.xml).
 """
         elif filename == 'all':
             insert_text += """
 # Dialect: all
 
-This dialect is intended to `include` all other [dialects](../messages/README.md) in the mavlink/mavlink repository (including [external dialects](https://github.com/mavlink/mavlink/tree/master/external/dialects#mavlink-external-dialects)).
+This dialect is intended to `include` all other [dialects](../messages/README.md) in the [mavlink/mavlink](https://github.com/mavlink/mavlink) repository (including [external dialects](https://github.com/mavlink/mavlink/tree/master/external/dialects#mavlink-external-dialects)).
 
 Dialects that are in **all.xml** are guaranteed to not have clashes in messages, enums, enum ids, and MAV_CMDs.
 This ensure that:
 
 - Systems based on these dialects can co-exist on the same MAVLink network.
 - A Ground Station might (optionally) use libraries generated from **all.xml** to communicate using any of the dialects.
 
-> **Warning** New dialect files in the official repository must be added to **all.xml** and restrict themselves to using ids in their own allocated range.
-A few older dialects are not included because these operate in completely closed networks or because they are only used for tests.
+> **Warning**
+>
+> - New dialect files in the official repository must be added to **all.xml** and restrict themselves to using ids in their own allocated range.
+> - Dialects should push changes to mavlink/mavlink in order to avoid potential clashes from changes to other dialects.
+>
+> A few older dialects are not included because these operate in completely closed networks or because they are only used for tests.
 
 This topic is a human-readable form of the XML definition file: [all.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/all.xml).
 """
+
+        elif filename == 'ardupilotmega':
+            insert_text += """
+# Dialect: ArduPilotMega
+
+> **Warning** [ardupilotmega.xml](https://github.com/ArduPilot/mavlink/blob/master/message_definitions/v1.0/ardupilotmega.xml) contains the accurate and up-to-date documentation for this dialect.
+> The documentation below may not be accurate if the dialect owner has not pushed changes.
+
+These messages define the [ArduPilot](http://ardupilot.org) specific dialect (as pushed to the [mavlink/mavlink](https://github.com/mavlink/mavlink) GitHub repository by the dialect owner).
+
+This topic is a human-readable form of the XML definition file: [ardupilotmega.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/ardupilotmega.xml).
+
+    """
+
+        elif filename == 'cubepilot':
+            insert_text += """
+# Dialect: cubepilot
+
+> **Warning** [cubepilot.xml](https://github.com/CubePilot/mavlink/blob/master/message_definitions/v1.0/cubepilot.xml) contains the accurate and up-to-date documentation for this dialect.
+> The documentation below may not be accurate if the dialect owner has not pushed changes.
+
+These messages define the [CubePilot](http://www.cubepilot.com) specific dialect (as pushed to the [mavlink/mavlink](https://github.com/mavlink/mavlink) GitHub repository by the dialect owner).
+
+This topic is a human-readable form of the XML definition file: [cubepilot.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/cubepilot.xml).
+
+    """
+
+
         else:
-            insert_text += '\n# Dialect: %s' % filename.rsplit('.', 1)[0]
-            insert_text += '\n\n*This is a human-readable form of the XML definition file: [%s](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/%s).*' % (
-                filename, filename)
+            dialectName = filename.rsplit('.', 1)[0]
+            filenameXML = f'{dialectName}.xml'
+            insert_text += f"""
+# Dialect: {dialectName}
+
+> **Warning** This topic documents the version of the dialect file in the [mavlink/mavlink](https://github.com/mavlink/mavlink) Github repository, which may not be up to date with the file in the source repository (it is up to the dialect owner to push changes when needed).
+> The source repo should be listed in the comments at the top of the XML definition file listed below (but may not be).
+
+This topic is a human-readable form of the XML definition file: [{filenameXML}](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/{filenameXML}).
+"""
         insert_text += """
 
 <span id="mav2_extension_field"></span>
@@ -357,7 +394,6 @@ def get_top_level_docs(self, filename):
 
         return insert_text
 
-
 class MAVDeprecated(object):
     def __init__(self, soup):
         # name, type, print_format, xml, description='', enum='', display='', units='', instance=False
@@ -564,8 +600,11 @@ def getMarkdown(self, currentDialect):
             # message+=f"Included from [{self.basename}](../messages/{self.basename}.md#{self.name})\n\n"  # With basename (dialect name) test
         message += ' {#' + self.name + '}\n\n'
 
-        # If dialect, that's it. After this is assuming current dialect
-        if self.basename is not currentDialect:
+        # If it is common we include everything.
+        # But for any other dialect we don't include the reset of the message
+        if currentDialect == 'common':
+            pass
+        elif self.basename is not currentDialect:
             return message
 
         if self.deprecated:
@@ -732,8 +771,11 @@ def getMarkdown(self, currentDialect):
             # message+=f"Included from [{self.basename}](../messages/{self.basename}.md#{self.name})\n\n"  # With basename (dialect name) test
         string += ' {#' + self.name + '}\n\n'
 
-        # If dialect, that's it. After this is assuming current dialect
-        if self.basename is not currentDialect:
+        # If it is common we include everything.
+        # But for any other dialect we don't include the reset of the message
+        if currentDialect == 'common':
+            pass
+        elif self.basename is not currentDialect:
             return string
 
         if self.deprecated:
@@ -874,10 +916,14 @@ def getMarkdown(self, currentDialect):
             string += " [WIP]"
         string += ' {#' + self.name + '}\n\n'
 
-        # If dialect, that's it. After this is assuming current dialect
-        if self.basename is not currentDialect:
+        # If it is common we include everything.
+        # But for any other dialect we don't include the reset of the message
+        if currentDialect == 'common':
+            pass
+        elif self.basename is not currentDialect:
             return string
 
+
         if self.deprecated:
             string += self.deprecated.getMarkdown() + "\n\n"
         if self.wip: