Less verbose doc generation

Author: pgleeson

examples/document.md

@@ -13,7 +13,7 @@ A model for documents.
   <tr>
     <td><b>title</b></td>
     <td>str</td>
-    <td><i>Document title</i></td>
+    <td><i>The document title</i></td>
  </tr>
 
 

examples/document.py

@@ -40,7 +40,7 @@ class Document(Base):
 
     Args:
         id: The unique id of the document
-        title: Document title
+        title: The document title
         ISBN: International Standard Book Number
         sections: The sections of the document
     """
@@ -65,24 +65,29 @@ class Document(Base):
 
 print(doc)
 print(doc.sections[0].paragraphs[0].contents)
-print(doc.sections[0].paragraphs[0].__getattribute__("contents"))
+print(doc.sections[0].paragraphs[1].__getattribute__("contents"))
 
 doc.to_json_file("document.json")
 doc.to_yaml_file("document.yaml")
 doc.to_bson_file("document.bson")
 
+print(" >> Full document details in YAML format:\n")
+
+print(doc.to_yaml())
+
 doc_md = doc.generate_documentation(format="markdown")
 
 with open("document.md", "w") as d:
     d.write(doc_md)
 
+
 doc_rst = doc.generate_documentation(format="rst")
 
 with open("document.rst", "w") as d:
     d.write(doc_rst)
 
 
-print("\nGenerating specification in dict form")
+print("\n  >> Generating specification in dict form...")
 doc_dict = doc.generate_documentation(format="dict")
 
 import json
@@ -92,9 +97,12 @@ class Document(Base):
 with open("document.specification.json", "w") as d:
     d.write(json.dumps(doc_dict, indent=4))
 
-print("Generating specification in YAML")
+print("  >> Generating specification in YAML...\n")
+
 with open("document.specification.yaml", "w") as d:
-    d.write(yaml.dump(doc_dict, indent=4, sort_keys=False))
+    yy = yaml.dump(doc_dict, indent=4, sort_keys=False)
+    print(yy)
+    d.write(yy)
 
 with open("document.specification.bson", "wb") as d:
     d.write(bson.encode(doc_dict))

examples/document.rst

@@ -9,7 +9,7 @@ A model for documents.
 Allowed field    Data Type    Description
 ===============  ===========  ==================================
 **id**           str          The unique id of the document
-**title**        str          Document title
+**title**        str          The document title
 **ISBN**         int          International Standard Book Number
 ===============  ===========  ==================================
 

examples/document.specification.json

@@ -8,7 +8,7 @@
             },
             "title": {
                 "type": "str",
-                "description": "Document title"
+                "description": "The document title"
             },
             "ISBN": {
                 "type": "int",

examples/document.specification.yaml

@@ -6,7 +6,7 @@ Document:
             description: The unique id of the document
         title:
             type: str
-            description: Document title
+            description: The document title
         ISBN:
             type: int
             description: International Standard Book Number

src/modelspec/base_types.py

@@ -584,7 +584,7 @@ def _cls_generate_documentation(cls, format: str = MARKDOWN_FORMAT):
         allowed_fields = cls._parse_allowed_fields()
         allowed_children = cls._parse_allowed_children()
 
-        print(f" - {cls.__name__} ({definition})")
+        # print(f" - {cls.__name__} ({definition})")
 
         rst_url_format = "`%s <%s>`__"
 
@@ -693,7 +693,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                 type_, can_be_eval_expr=True, can_be_dict=True
             )
             type_str = Base._type_to_str(type_)
-            print("    Allowed parameter: {} {}".format(f, (description, type_str)))
+            # print("    Allowed parameter: {} {}".format(f, (description, type_str)))
 
             if format == DICT_FORMAT:
                 doc_dict[name]["allowed_parameters"][f] = {}
@@ -750,7 +750,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
 
         for c, (description, type_) in allowed_children.items():
             type_str = Base._type_to_str(type_)
-            print("    Allowed child: {} {}".format(c, (description, type_str)))
+            # print("    Allowed child: {} {}".format(c, (description, type_str)))
 
             referencable = not Base._is_base_type(type_, can_be_dict=True)