Update formatting of generated docs

Author: pgleeson

examples/document.md

@@ -1,42 +1,77 @@
 ## Document
 A model for documents
 
-#### Allowed parameters
-<table><tr><td><b>id</b></td><td>str</td><td><i>The unique id of the document</i></td></tr>
+### Allowed parameters
+<table>
+  <tr>
+    <td><b>id</b></td>
+    <td>str</td>
+    <td><i>The unique id of the document</i></td>
+ </tr>
 
-<tr><td><b>title</b></td><td>str</td><td><i>Document title</i></td></tr>
 
-<tr><td><b>ISBN</b></td><td>int</td><td><i>International Standard Book Number</i></td></tr>
+  <tr>
+    <td><b>title</b></td>
+    <td>str</td>
+    <td><i>Document title</i></td>
+ </tr>
+
+
+  <tr>
+    <td><b>ISBN</b></td>
+    <td>int</td>
+    <td><i>International Standard Book Number</i></td>
+ </tr>
 
 
 </table>
 
-#### Allowed children
-<table><tr><td><b>sections</b></td><td><a href="#section">Section</a></td><td><i>The sections of the document</i></td></tr>
+### Allowed children
+<table>
+  <tr>
+    <td><b>sections</b></td>
+    <td><a href="#section">Section</a></td>
+    <td><i>The sections of the document</i></td>
+  </tr>
 
 
 </table>
 
 ## Section
 A model of a section of the document. Will contain a <a href="#paragraph">Paragraph</a> or two
 
-#### Allowed parameters
-<table><tr><td><b>id</b></td><td>str</td><td><i>The id of the section</i></td></tr>
+### Allowed parameters
+<table>
+  <tr>
+    <td><b>id</b></td>
+    <td>str</td>
+    <td><i>The id of the section</i></td>
+ </tr>
 
 
 </table>
 
-#### Allowed children
-<table><tr><td><b>paragraphs</b></td><td><a href="#paragraph">Paragraph</a></td><td><i>The paragraphs</i></td></tr>
+### Allowed children
+<table>
+  <tr>
+    <td><b>paragraphs</b></td>
+    <td><a href="#paragraph">Paragraph</a></td>
+    <td><i>The paragraphs</i></td>
+  </tr>
 
 
 </table>
 
 ## Paragraph
 A model of a paragraph
 
-#### Allowed parameters
-<table><tr><td><b>contents</b></td><td>str</td><td><i>Paragraph contents, which make up the <a href="#section">Section</a>s.</i></td></tr>
+### Allowed parameters
+<table>
+  <tr>
+    <td><b>contents</b></td>
+    <td>str</td>
+    <td><i>Paragraph contents, which make up the <a href="#section">Section</a>s.</i></td>
+ </tr>
 
 
 </table>

src/modelspec/base_types.py

@@ -563,7 +563,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
 
         if len(allowed_fields) > 0:
             if format == MARKDOWN_FORMAT:
-                doc_string += "#### Allowed parameters\n<table>"
+                doc_string += "### Allowed parameters\n<table>"
             if format == RST_FORMAT:
                 ap = "**Allowed parameters**"
                 doc_string += "%s\n\n" % (ap)
@@ -586,13 +586,15 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                 doc_dict[name]["allowed_parameters"][f]["description"] = description
 
             elif format == MARKDOWN_FORMAT:
-                doc_string += "<tr><td><b>{}</b></td><td>{}</td>".format(
-                    f,
-                    f'<a href="#{type_str.lower()}">{type_str}</a>'
-                    if referencable
-                    else type_str,
+                doc_string += (
+                    "\n  <tr>\n    <td><b>{}</b></td>\n    <td>{}</td>".format(
+                        f,
+                        f'<a href="#{type_str.lower()}">{type_str}</a>'
+                        if referencable
+                        else type_str,
+                    )
                 )
-                doc_string += "<td><i>%s</i></td></tr>\n\n" % (
+                doc_string += "\n    <td><i>%s</i></td>\n </tr>\n\n" % (
                     insert_links(description)
                 )
 
@@ -623,7 +625,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
 
         if len(allowed_children) > 0:
             if format == MARKDOWN_FORMAT:
-                doc_string += "#### Allowed children\n<table>"
+                doc_string += "### Allowed children\n<table>"
             elif format == RST_FORMAT:
                 ap = "**Allowed children**"
                 doc_string += "%s\n\n" % (ap)
@@ -645,13 +647,15 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                 ][0]
 
             elif format == MARKDOWN_FORMAT:
-                doc_string += "<tr><td><b>{}</b></td><td>{}</td>".format(
-                    c,
-                    f'<a href="#{type_str.lower()}">{type_str}</a>'
-                    if referencable
-                    else type_str,
+                doc_string += (
+                    "\n  <tr>\n    <td><b>{}</b></td>\n    <td>{}</td>".format(
+                        c,
+                        f'<a href="#{type_str.lower()}">{type_str}</a>'
+                        if referencable
+                        else type_str,
+                    )
                 )
-                doc_string += "<td><i>%s</i></td></tr>\n\n" % (
+                doc_string += "\n    <td><i>%s</i></td>\n  </tr>\n\n" % (
                     insert_links(description)
                 )