Merge pull request #10 from ModECI/development

Fix export as dict->json/yaml; to v0.2.3

Author: pgleeson

README.md

@@ -4,8 +4,8 @@
 [![Continuous builds](https://github.com/ModECI/modelspec/actions/workflows/ci.yml/badge.svg)](https://github.com/ModECI/modelspec/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/modelspec)](https://pypi.org/project/modelspec/)
 
 
-Functionality for specifying models & enabling automatic serialization (e.g. in JSON and YAML format).
+Functionality for specifying the structure of models & enabling automatic serialization to them (e.g. in JSON and YAML format).
 
 This package is being used by [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF).
 
-
+For an example of the use of this package see [here](examples/README.md).

examples/README.md

@@ -1,3 +1,49 @@
-## Some simple examples of the use of Modelspec
+# Some simple examples of the use of Modelspec
 
 See also packages [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF) for usage of Modelspec.
+
+## A simple definition of the structure of a Document in modelspec
+
+### 1) Define the structure of a "Document"
+
+A Python file defining the structure of the Document, as well as saving an instance (see below) can be found here: [document.py](document.py).
+
+
+### 2) Generate human and machine readable specifications of what can be in a Document
+
+A generated Markdown file where the structure of a Document is defined is here: [document.md](document.md). To generate this:
+```
+    doc_md = doc.generate_documentation(format="markdown")
+```
+
+A similar file can be done in reStructuredText (RST) format ([document.rst](document.rst))
+```
+    doc_rst = doc.generate_documentation(format="rst")
+```
+
+For a machine readable version of this, generate in dict format and save to [YAML](document.specification.yaml) or [JSON](document.specification.json).
+```
+doc_dict = doc.generate_documentation(format="dict")
+
+with open("document.specification.json", "w") as d:
+    d.write(json.dumps(doc_dict, indent=4))
+
+with open("document.specification.yaml", "w") as d:
+    d.write(yaml.dump(doc_dict, indent=4, sort_keys=False))
+```
+
+### 3) Create an instance of a Document
+
+The actual instance of a document which is built (in [document.py](document.py)) can be saved in [YAML](document.yaml) or [JSON](document.json) format:
+```
+doc = Document(id="MyBook")
+doc.title = "My life in Python"
+
+a = Section(id="Abstract")
+doc.sections.append(a)
+
+...
+
+doc.to_json_file("document.json")
+doc.to_yaml_file("document.yaml")
+```

examples/document.py

@@ -76,3 +76,17 @@ class Document(Base):
 
 with open("document.rst", "w") as d:
     d.write(doc_rst)
+
+
+print("\nGenerating specification in dict form")
+doc_dict = doc.generate_documentation(format="dict")
+
+import json
+import yaml
+
+with open("document.specification.json", "w") as d:
+    d.write(json.dumps(doc_dict, indent=4))
+
+print("Generating specification in YAML")
+with open("document.specification.yaml", "w") as d:
+    d.write(yaml.dump(doc_dict, indent=4, sort_keys=False))

examples/document.specification.json

@@ -0,0 +1,49 @@
+{
+    "Document": {
+        "definition": "A model for documents",
+        "allowed_parameters": {
+            "id": {
+                "type": "str",
+                "description": "The unique id of the document"
+            },
+            "title": {
+                "type": "str",
+                "description": "Document title"
+            },
+            "ISBN": {
+                "type": "int",
+                "description": "International Standard Book Number"
+            }
+        },
+        "allowed_children": {
+            "sections": {
+                "type": "Section",
+                "description": "The sections of the document"
+            }
+        }
+    },
+    "Section": {
+        "definition": "A model of a section of the :class:`Document`. Will contain one :class:`Paragraph` or more",
+        "allowed_parameters": {
+            "id": {
+                "type": "str",
+                "description": "The id of the section"
+            }
+        },
+        "allowed_children": {
+            "paragraphs": {
+                "type": "Paragraph",
+                "description": "The paragraphs"
+            }
+        }
+    },
+    "Paragraph": {
+        "definition": "A model of a paragraph",
+        "allowed_parameters": {
+            "contents": {
+                "type": "str",
+                "description": "Paragraph contents, which make up the _Section_s."
+            }
+        }
+    }
+}

examples/document.specification.yaml

@@ -0,0 +1,33 @@
+Document:
+    definition: A model for documents
+    allowed_parameters:
+        id:
+            type: str
+            description: The unique id of the document
+        title:
+            type: str
+            description: Document title
+        ISBN:
+            type: int
+            description: International Standard Book Number
+    allowed_children:
+        sections:
+            type: Section
+            description: The sections of the document
+Section:
+    definition: A model of a section of the :class:`Document`. Will contain one :class:`Paragraph`
+        or more
+    allowed_parameters:
+        id:
+            type: str
+            description: The id of the section
+    allowed_children:
+        paragraphs:
+            type: Paragraph
+            description: The paragraphs
+Paragraph:
+    definition: A model of a paragraph
+    allowed_parameters:
+        contents:
+            type: str
+            description: Paragraph contents, which make up the _Section_s.

src/modelspec/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from .base_types import Base, define, has, field, fields, optional, instance_of, in_
 

src/modelspec/base_types.py

@@ -721,6 +721,8 @@ def insert_links(text, format=MARKDOWN_FORMAT):
         for r in referenced:
             if format in (MARKDOWN_FORMAT, RST_FORMAT):
                 doc_string += r._cls_generate_documentation(format=format)
+            if format in (DICT_FORMAT):
+                doc_dict.update(r._cls_generate_documentation(format=format))
 
         if format in (MARKDOWN_FORMAT, RST_FORMAT):
             return doc_string