Merge pull request #19 from ModECI/development

To v0.2.6; multiple docstring handling updates

Author: pgleeson

examples/README.md

@@ -34,7 +34,7 @@ with open("document.specification.yaml", "w") as d:
 
 ### 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:
+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 or [BSON](document.bson) format:
 ```
 doc = Document(id="MyBook")
 doc.title = "My life in Python"
@@ -46,4 +46,5 @@ doc.sections.append(a)
 
 doc.to_json_file("document.json")
 doc.to_yaml_file("document.yaml")
+doc.to_bson_file("document.bson")
 ```

examples/document.md

@@ -38,7 +38,7 @@ A model for documents.
 </table>
 
 ## Section
-A model of a section of the <a href="#document">Document</a>. Will contain one <a href="#paragraph">Paragraph</a> or more.
+A model of a section of the <a href="#document">Document</a>. Will contain one <a href="#paragraph">Paragraph</a> or more, i.e the <a href="#paragraph">Paragraph</a>(s) in the section, probably related to the <b>title</b> of the `Document <#document>`_.
 
 ### Allowed parameters
 <table>

examples/document.py

@@ -12,7 +12,7 @@ class Paragraph(Base):
     A model of a paragraph.
 
     Args:
-        contents: Paragraph contents, which make up the _Section_s.
+        contents: Paragraph contents, which make up the :class:`Section`s.
     """
 
     contents: str = field(validator=instance_of(str))
@@ -22,7 +22,7 @@ class Paragraph(Base):
 class Section(Base):
     """
     A model of a section of the :class:`Document`.
-    Will contain one :class:`Paragraph` or more.
+    Will contain one :class:`Paragraph` or more, i.e the :class:`Paragraph`(s) in the section, probably related to the :code:`title` of the `Document <#document>`_.
 
     Args:
         id: The id of the section

examples/document.rst

@@ -5,42 +5,42 @@ A model for documents.
 
 **Allowed parameters**
 
-===============  ===========  ====================================
+===============  ===========  ==================================
 Allowed field    Data Type    Description
-===============  ===========  ====================================
-**id**           str          *The unique id of the document*
-**title**        str          *Document title*
-**ISBN**         int          *International Standard Book Number*
-===============  ===========  ====================================
+===============  ===========  ==================================
+**id**           str          The unique id of the document
+**title**        str          Document title
+**ISBN**         int          International Standard Book Number
+===============  ===========  ==================================
 
 **Allowed children**
 
-===============  =====================  ==============================
-Allowed child    Data Type              Description
-===============  =====================  ==============================
-**sections**     `Section <#section>`_  *The sections of the document*
-===============  =====================  ==============================
+===============  ======================  ============================
+Allowed child    Data Type               Description
+===============  ======================  ============================
+**sections**     `Section <#section>`__  The sections of the document
+===============  ======================  ============================
 
 =======
 Section
 =======
-A model of a section of the <a href="#document">Document</a>. Will contain one <a href="#paragraph">Paragraph</a> or more.
+A model of a section of the `Document <#document>`__. Will contain one `Paragraph <#paragraph>`__ or more, i.e the `Paragraph(s) <#paragraph>`__ in the section, probably related to the **title** of the `Document <#document>`_.
 
 **Allowed parameters**
 
-===============  ===========  =======================
+===============  ===========  =====================
 Allowed field    Data Type    Description
-===============  ===========  =======================
-**id**           str          *The id of the section*
-===============  ===========  =======================
+===============  ===========  =====================
+**id**           str          The id of the section
+===============  ===========  =====================
 
 **Allowed children**
 
-===============  =========================  ================
-Allowed child    Data Type                  Description
-===============  =========================  ================
-**paragraphs**   `Paragraph <#paragraph>`_  *The paragraphs*
-===============  =========================  ================
+===============  ==========================  ==============
+Allowed child    Data Type                   Description
+===============  ==========================  ==============
+**paragraphs**   `Paragraph <#paragraph>`__  The paragraphs
+===============  ==========================  ==============
 
 =========
 Paragraph
@@ -49,8 +49,8 @@ A model of a paragraph.
 
 **Allowed parameters**
 
-===============  ===========  =================================================
+===============  ===========  ==============================================================
 Allowed field    Data Type    Description
-===============  ===========  =================================================
-**contents**     str          *Paragraph contents, which make up the Sections.*
-===============  ===========  =================================================
+===============  ===========  ==============================================================
+**contents**     str          Paragraph contents, which make up the `Sections <#section>`__.
+===============  ===========  ==============================================================

examples/document.specification.json

@@ -23,7 +23,7 @@
         }
     },
     "Section": {
-        "definition": "A model of a section of the :class:`Document`. Will contain one :class:`Paragraph` or more.",
+        "definition": "A model of a section of the :class:`Document`. Will contain one :class:`Paragraph` or more, i.e the :class:`Paragraph`(s) in the section, probably related to the :code:`title` of the `Document <#document>`_.",
         "allowed_parameters": {
             "id": {
                 "type": "str",
@@ -42,7 +42,7 @@
         "allowed_parameters": {
             "contents": {
                 "type": "str",
-                "description": "Paragraph contents, which make up the _Section_s."
+                "description": "Paragraph contents, which make up the :class:`Section`s."
             }
         }
     }

examples/document.specification.yaml

@@ -16,7 +16,8 @@ Document:
             description: The sections of the document
 Section:
     definition: A model of a section of the :class:`Document`. Will contain one :class:`Paragraph`
-        or more.
+        or more, i.e the :class:`Paragraph`(s) in the section, probably related to
+        the :code:`title` of the `Document <#document>`_.
     allowed_parameters:
         id:
             type: str
@@ -30,4 +31,4 @@ Paragraph:
     allowed_parameters:
         contents:
             type: str
-            description: Paragraph contents, which make up the _Section_s.
+            description: Paragraph contents, which make up the :class:`Section`s.

src/modelspec/__init__.py

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

src/modelspec/base_types.py

@@ -373,6 +373,9 @@ def _parse_definition(cls) -> str:
         p = parse(cls.__doc__)
 
         # Extract the description, use the long description if available.
+        # "short_description" only parse the first non-empty line and
+        # "long_description" parse the rest of the docstring i.e.
+        # it skips the first non-empty line and parse the rest of the docstring
         if p.long_description:
             definition = f"{p.short_description} {p.long_description}"
         else:
@@ -578,7 +581,7 @@ def _cls_generate_documentation(cls, format: str = MARKDOWN_FORMAT):
 
         print(f" - {cls.__name__} ({definition})")
 
-        rst_url_format = "`%s <%s>`_"
+        rst_url_format = "`%s <%s>`__"
 
         def insert_links(text, format=MARKDOWN_FORMAT):
 
@@ -591,7 +594,12 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                 pre = text2[0:ind]
                 ref = text2[ind + len(code_ref) : ind2]
                 post = text2[ind2 + 1 :]
-                text2 = f"{pre}<b>{ref}</b>{post}"
+
+                if format == MARKDOWN_FORMAT:
+                    text2 = f"{pre}<b>{ref}</b>{post}"
+                elif format == RST_FORMAT:
+                    text2 = f"{pre}**{ref}**{post}"
+
             # print("    > Converted to: %s" % text2)
             text = text2
 
@@ -606,28 +614,44 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                 if ref[0] == "~":
                     ref = ref[1:]
                 post = text2[ind2 + 1 :]
-                text2 = f'{pre}<a href="#{ref.lower()}">{ref}</a>{post}'
+                if format == MARKDOWN_FORMAT:
+                    text2 = f'{pre}<a href="#{ref.lower()}">{ref}</a>{post}'
+                elif format == RST_FORMAT:
+                    rr = ref
+                    pp = post
+
+                    ######################################
+                    # Some hardcoded fixes for plurals...
+                    if pp.startswith("s "):
+                        rr += "s"
+                        pp = pp[1:]
+                    if pp.startswith("s."):
+                        rr += "s"
+                        pp = pp[1:]
+                    if pp.startswith("(s)"):
+                        rr += "(s)"
+                        pp = pp[3:]
+                    ######################################
+
+                    text2 = f"{pre}`{rr} <#{ref.lower()}>`__{pp}"
+
             # print("    > Converted to: %s" % text2)
             text = text2
 
             if "_" not in text:
                 return text
             if '"' in text:
                 return text  # Assume it's a quoted string containing an underscore...
+            if format == RST_FORMAT:
+                return text  # No need to remove underscore for RST format
+
             split = text.split("_")
             text2 = ""
             for i in range(int(len(split) / 2.0)):
                 pre = split[i * 2]
                 type = split[i * 2 + 1]
-                if format == MARKDOWN_FORMAT:
-                    text2 += f'{pre}<a href="#{type.lower()}">{type}</a>'
-                elif format == RST_FORMAT:
-                    # text2 += ('%s'+rst_url_format) % (pre, type, '#'+type.lower # problem with handling links ending with s e.g. _Graph_s
+                text2 += f'{pre}<a href="#{type.lower()}">{type}</a>'
 
-                    text2 += ("%s%s") % (
-                        pre,
-                        type,
-                    )  # temp hack... problem with handling links ending with s e.g. _Graph_s
             if int(len(split) / 2.0) != len(split) / 2.0:
                 text2 += split[-1]
             return text2
@@ -691,7 +715,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                     if referencable
                     else type_str,
                 )
-                d = "*%s*" % (insert_links(description, format=RST_FORMAT))
+                d = "%s" % (insert_links(description, format=RST_FORMAT))
                 table_info.append([n, t, d])
 
             if referencable:
@@ -752,7 +776,7 @@ def insert_links(text, format=MARKDOWN_FORMAT):
                     if referencable
                     else type_str,
                 )
-                d = "*%s*" % (insert_links(description, format=RST_FORMAT))
+                d = "%s" % (insert_links(description, format=RST_FORMAT))
                 table_info.append([n, t, d])
 
             # Get the contained type

src/modelspec/utils.py

@@ -221,17 +221,19 @@ def evaluate(expr, parameters={}, rng=None, array_format=FORMAT_NUMPY, verbose=F
     if array_format == FORMAT_TENSORFLOW:
         import tensorflow as tf
 
-    print_(
-        " > Evaluating: [%s] which is a: %s, vs parameters: %s (using %s arrays)..."
-        % (expr, type(expr).__name__, _params_info(parameters), array_format),
-        verbose,
-    )
+    if verbose:
+        print_(
+            " > Evaluating: [%s] which is a: %s, vs parameters: %s (using %s arrays)..."
+            % (expr, type(expr).__name__, _params_info(parameters), array_format),
+            verbose,
+        )
     try:
         if type(expr) == str and expr in parameters:
             expr = parameters[
                 expr
             ]  # replace with the value in parameters & check whether it's float/int...
-            print_("Using for that param: %s" % _val_info(expr), verbose)
+            if verbose:
+                print_("Using for that param: %s" % _val_info(expr), verbose)
 
         if type(expr) == str:
             try:
@@ -250,33 +252,39 @@ def evaluate(expr, parameters={}, rng=None, array_format=FORMAT_NUMPY, verbose=F
                 pass
 
         if type(expr) == list:
-            print_("Returning a list in format: %s" % array_format, verbose)
+            if verbose:
+                print_("Returning a list in format: %s" % array_format, verbose)
             if array_format == FORMAT_TENSORFLOW:
                 return tf.constant(expr, dtype=tf.float64)
             else:
                 return np.array(expr)
 
         if type(expr) == np.ndarray:
-            print_("Returning a numpy array in format: %s" % array_format, verbose)
+            if verbose:
+                print_("Returning a numpy array in format: %s" % array_format, verbose)
             if array_format == FORMAT_TENSORFLOW:
                 return tf.convert_to_tensor(expr, dtype=tf.float64)
             else:
                 return np.array(expr)
 
         if "Tensor" in type(expr).__name__:
-            print_(
-                "Returning a tensorflow Tensor in format: %s" % array_format, verbose
-            )
+            if verbose:
+                print_(
+                    "Returning a tensorflow Tensor in format: %s" % array_format,
+                    verbose,
+                )
             if array_format == FORMAT_NUMPY:
                 return expr.numpy()
             else:
                 return expr
 
         if int(expr) == expr:
-            print_("Returning int: %s" % int(expr), verbose)
+            if verbose:
+                print_("Returning int: %s" % int(expr), verbose)
             return int(expr)
         else:  # will have failed if not number
-            print_("Returning float: %s" % expr, verbose)
+            if verbose:
+                print_("Returning float: %s" % expr, verbose)
             return float(expr)
     except:
         try:
@@ -289,24 +297,33 @@ def evaluate(expr, parameters={}, rng=None, array_format=FORMAT_NUMPY, verbose=F
             if type(expr) == str and "numpy." in expr:
                 parameters["numpy"] = np
 
-            print_(
-                "Trying to eval [%s] with Python using %s..."
-                % (expr, parameters.keys()),
-                verbose,
-            )
+            if verbose:
+                print_(
+                    "Trying to eval [%s] with Python using %s..."
+                    % (expr, parameters.keys()),
+                    verbose,
+                )
 
             v = eval(expr, parameters)
-            print_("Evaluated with Python: {} = {}".format(expr, _val_info(v)), verbose)
+
+            if verbose:
+                print_(
+                    "Evaluated with Python: {} = {}".format(expr, _val_info(v)), verbose
+                )
+
             if (type(v) == float or type(v) == str) and int(v) == v:
-                print_("Returning int: %s" % int(v), verbose)
+
+                if verbose:
+                    print_("Returning int: %s" % int(v), verbose)
 
                 if array_format == FORMAT_TENSORFLOW:
                     return tf.constant(int(v))
                 else:
                     return int(v)
             return v
         except Exception as e:
-            print_(f"Returning without altering: {expr} (error: {e})", verbose)
+            if verbose:
+                print_(f"Returning without altering: {expr} (error: {e})", verbose)
             return expr