Improve formatting of documentation, fix #49

Signed-off-by: Roberto Di Remigio <roberto.diremigio@gmail.com>

parselglossy/documentation.py

@@ -51,14 +51,19 @@ def documentation_generator(
     """
 
     comment = (
+        ".. raw:: html\n\n"
+        "    <style> .red {color:#aa0060; font-weight:bold; font-size:18px} </style>\n\n"
+        ".. role:: red\n\n"
         ".. This documentation was autogenerated using parselglossy."
         " Editing by hand is not recommended.\n"
     )
 
     header_fmt = (
         "{comment:s}\n{markup:s}\n{header:s}\n{markup:s}\n\n"
-        "Keywords without a default value are **required**.\n"
-        "Sections where all keywords have a default value can be omitted.\n"
+        "- Keywords without a default value are **required**.\n"
+        "- Default values are either explicit or computed from the value of other keywords in the input.\n"
+        "- Sections where all keywords have a default value can be omitted.\n"
+        "- Predicates, if present, are the functions run to validate user input.\n"
     )
 
     docs = rec_documentation_generator(template=template)
@@ -82,10 +87,20 @@ def document_keyword(keyword: JSONDict) -> str:
 
     if "default" in keyword.keys():
         doc += """
-  **Default** {}""".format(
+  **Default** ``{}``
+""".format(
             keyword["default"]
         )
 
+    if "predicates" in keyword.keys():
+        preds = "\n    ".join(("- ``{}``".format(x) for x in keyword["predicates"]))
+        doc += """
+  **Predicates**
+    {}
+""".format(
+            preds
+        )
+
     return doc
 
 
@@ -106,20 +121,20 @@ def rec_documentation_generator(template, *, level: int = 0) -> str:
 
     keywords = template["keywords"] if "keywords" in template.keys() else []
     if keywords:
-        doc = "\n**Keywords**"
+        docs.append(indent("\n:red:`Keywords`", level))
+
     for k in keywords:
-        doc += document_keyword(k)
+        doc = document_keyword(k)
         docs.extend(indent(doc, level))
 
     sections = template["sections"] if "sections" in template.keys() else []
     if sections:
-        doc = "\n" if level == 0 else "\n\n"
-        doc += "**Sections**"
+        docs.append(indent("\n:red:`Sections`", level))
         fmt = r"""
  :{0:s}: {1:s}
 """
         for s in sections:
-            doc += fmt.format(s["name"], s["docstring"])
+            doc = fmt.format(s["name"], s["docstring"])
             doc += rec_documentation_generator(s, level=level + 1)
             docs.extend(indent(doc, level))
 

tests/api/docs_template.yml

@@ -2,19 +2,52 @@ keywords:
 - docstring: Title of the calculation.
   name: title
   type: str
+- docstring: Some integer
+  name: an_integer
+  type: int
+  default: 15
+- docstring: A list of floats
+  name: float_list
+  type: List[float]
+  default: [1.0, 2.0, 3.0]
+  predicates:
+    - "len(value) < 10"
+    - "max(value) < user['foo']['fooffa]['another_float']"
 sections:
 - docstring: brilliant
+  name: foo
   keywords:
   - default: Wham! Bang! Pow! Let's Rock Out!
     docstring: Title of the calculation.
     name: tragic
     type: str
-  name: foo
+  - name: a_float
+    type: float
+    docstring: A floating point number
+    predicates:
+      - "value < 35.0"
+      - "value in user['float_list']"
   sections:
   - docstring: A ba-bar section
+    name: Bar
     keywords:
     - default: Bobson Dugnutt
       docstring: Title of the calculation.
       name: amazing
       type: str
-    name: Bar
+    - name: coolio
+      type: bool
+      docstring: A cool bool
+      default: True
+- docstring: nothing really
+  name: fooffa
+  keywords:
+  - name: dwigt
+    docstring: An unusual name
+    type: str
+    predicates:
+      - "len(value) < 80"
+  - name: another_float
+    type: float
+    docstring: Another floating point number
+    default: "user['foo']['a_float'] * 2"

tests/cli/docs_template.yml

@@ -0,0 +1 @@
+../api/docs_template.yml

tests/ref/dwigt.rst

@@ -1,33 +1,88 @@
+.. raw:: html
+
+    <style> .red {color:#aa0060; font-weight:bold; font-size:18px} </style>
+
+.. role:: red
+
 .. This documentation was autogenerated using parselglossy. Editing by hand is not recommended.
 
 ==========================================
 Dwigt Rortugal's guide to input parameters
 ==========================================
 
-Keywords without a default value are **required**.
-Sections where all keywords have a default value can be omitted.
+- Keywords without a default value are **required**.
+- Default values are either explicit or computed from the value of other keywords in the input.
+- Sections where all keywords have a default value can be omitted.
+- Predicates, if present, are the functions run to validate user input.
 
-**Keywords**
+:red:`Keywords`
  :title: Title of the calculation.
 
   **Type** ``str``
 
-**Sections**
+ :an_integer: Some integer
+
+  **Type** ``int``
+
+  **Default** ``15``
+
+ :float_list: A list of floats
+
+  **Type** ``List[float]``
+
+  **Default** ``[1.0, 2.0, 3.0]``
+
+  **Predicates**
+    - ``len(value) < 10``
+    - ``max(value) < user['foo']['fooffa]['another_float']``
+
+:red:`Sections`
  :foo: brilliant
 
-  **Keywords**
+  :red:`Keywords`
    :tragic: Title of the calculation.
 
     **Type** ``str``
 
-    **Default** Wham! Bang! Pow! Let's Rock Out!
+    **Default** ``Wham! Bang! Pow! Let's Rock Out!``
+
+   :a_float: A floating point number
+
+    **Type** ``float``
 
-  **Sections**
+    **Predicates**
+      - ``value < 35.0``
+      - ``value in user['float_list']``
+
+  :red:`Sections`
    :Bar: A ba-bar section
 
-      **Keywords**
+      :red:`Keywords`
        :amazing: Title of the calculation.
 
         **Type** ``str``
 
-        **Default** Bobson Dugnutt
+        **Default** ``Bobson Dugnutt``
+
+       :coolio: A cool bool
+
+        **Type** ``bool``
+
+        **Default** ``True``
+
+ :fooffa: nothing really
+
+  :red:`Keywords`
+   :dwigt: An unusual name
+
+    **Type** ``str``
+
+    **Predicates**
+      - ``len(value) < 80``
+
+   :another_float: Another floating point number
+
+    **Type** ``float``
+
+    **Default** ``user['foo']['a_float'] * 2``
+

tests/ref/input.rst

@@ -1,33 +1,88 @@
+.. raw:: html
+
+    <style> .red {color:#aa0060; font-weight:bold; font-size:18px} </style>
+
+.. role:: red
+
 .. This documentation was autogenerated using parselglossy. Editing by hand is not recommended.
 
 ================
 Input parameters
 ================
 
-Keywords without a default value are **required**.
-Sections where all keywords have a default value can be omitted.
+- Keywords without a default value are **required**.
+- Default values are either explicit or computed from the value of other keywords in the input.
+- Sections where all keywords have a default value can be omitted.
+- Predicates, if present, are the functions run to validate user input.
 
-**Keywords**
+:red:`Keywords`
  :title: Title of the calculation.
 
   **Type** ``str``
 
-**Sections**
+ :an_integer: Some integer
+
+  **Type** ``int``
+
+  **Default** ``15``
+
+ :float_list: A list of floats
+
+  **Type** ``List[float]``
+
+  **Default** ``[1.0, 2.0, 3.0]``
+
+  **Predicates**
+    - ``len(value) < 10``
+    - ``max(value) < user['foo']['fooffa]['another_float']``
+
+:red:`Sections`
  :foo: brilliant
 
-  **Keywords**
+  :red:`Keywords`
    :tragic: Title of the calculation.
 
     **Type** ``str``
 
-    **Default** Wham! Bang! Pow! Let's Rock Out!
+    **Default** ``Wham! Bang! Pow! Let's Rock Out!``
+
+   :a_float: A floating point number
+
+    **Type** ``float``
 
-  **Sections**
+    **Predicates**
+      - ``value < 35.0``
+      - ``value in user['float_list']``
+
+  :red:`Sections`
    :Bar: A ba-bar section
 
-      **Keywords**
+      :red:`Keywords`
        :amazing: Title of the calculation.
 
         **Type** ``str``
 
-        **Default** Bobson Dugnutt
+        **Default** ``Bobson Dugnutt``
+
+       :coolio: A cool bool
+
+        **Type** ``bool``
+
+        **Default** ``True``
+
+ :fooffa: nothing really
+
+  :red:`Keywords`
+   :dwigt: An unusual name
+
+    **Type** ``str``
+
+    **Predicates**
+      - ``len(value) < 80``
+
+   :another_float: Another floating point number
+
+    **Type** ``float``
+
+    **Default** ``user['foo']['a_float'] * 2``
+