feat: can had comments with family/variable description in examples doc

src/rougail/output_doc/config.py

@@ -133,6 +133,23 @@ doc:
 
   change_default_value: true  # {_('Modify values to document leaderships and dynamics families')}
 
+  comment_examples:
+    description: {_('Add description of variables and families when generate examples')}
+    default: false
+    disabled:
+      jinja: |-
+        {{{{ "example" not in _.contents }}}}
+      return_type: boolean
+      description: {_('disabled when example in not in contents')}
+
+  comment_column:
+    description: {_('Comment starts at column')}
+    default: 30
+    disabled:
+      variable: _.comment_examples
+      propertyerror: true
+      when: false
+
   output_format:
     description: {_('Generate document in format')}
     alternative_name: do

src/rougail/output_doc/doc.py

@@ -87,6 +87,10 @@ class RougailOutputDoc(Examples, Changelog):
         self.contents = rougailconfig["doc.contents"]
         self.root = rougailconfig["doc.root"]
         self.example = "example" in self.contents
+        if self.example:
+            self.comment_examples = rougailconfig["doc.comment_examples"]
+            if self.comment_examples:
+                self.comment_column = rougailconfig["doc.comment_column"]
         if "variables" in self.contents:
             self.with_family = not rougailconfig["doc.without_family"]
         else:

src/rougail/output_doc/example.py

@@ -17,6 +17,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """
 
 from typing import Optional
+from ruamel.yaml import CommentedMap
 
 from .utils import _, calc_path
 
@@ -57,17 +58,20 @@ class Examples:  # pylint: disable=no-member,too-few-public-methods
         self.examples_mandatories = examples_mandatories
 
     def _parse_examples(self, dico, dyn_parent: Optional[str] = None) -> tuple:
-        examples = {}
+        if self.comment_examples:
-        examples_mandatories = {}
+            examples = CommentedMap()
+            examples_mandatories = CommentedMap()
+        else:
+            examples = {}
+            examples_mandatories = {}
         for value in dico.values():
             if value["type"] == "variable":
-                self._parse_examples_variable(
+                parse = self._parse_examples_variable
-                    value, dyn_parent, examples, examples_mandatories
-                )
             else:
-                self._parse_examples_family(
+                parse = self._parse_examples_family
-                    value, dyn_parent, examples, examples_mandatories
+            parse(
-                )
+                value, dyn_parent, examples, examples_mandatories
+            )
         return examples, examples_mandatories
 
     def _parse_examples_variable(
@@ -94,8 +98,18 @@ class Examples:  # pylint: disable=no-member,too-few-public-methods
                 name = variable["names"][idx]
             value = variable["example"][idx]
             examples[name] = value
+            if self.comment_examples and "description" in variable:
+                description = variable["description"]
+                if description.endswith('.'):
+                    description = description[:-1]
+                examples.yaml_add_eol_comment(description, name, column=self.comment_column)
             if variable["mandatory_without_value"]:
                 examples_mandatories[name] = value
+                if self.comment_examples and "description" in variable:
+                    description = variable["description"]
+                    if description.endswith('.'):
+                        description = description[:-1]
+                    examples_mandatories.yaml_add_eol_comment(description, name, column=self.comment_column)
             break
 
     def _parse_examples_family(
@@ -123,8 +137,18 @@ class Examples:  # pylint: disable=no-member,too-few-public-methods
             )
             if ret_m:
                 examples_mandatories[name] = ret_m
+                if self.comment_examples and "description" in family["informations"]:
+                    description = family["informations"]["description"]
+                    if description.endswith('.'):
+                        description = description[:-1]
+                    examples_mandatories.yaml_add_eol_comment(description, name, column=self.comment_column)
             if ret_e:
                 examples[name] = ret_e
+                if self.comment_examples and "description" in family["informations"]:
+                    description = family["informations"]["description"]
+                    if description.endswith('.'):
+                        description = description[:-1]
+                    examples.yaml_add_eol_comment(description, name, column=self.comment_column)
 
         ori_path = family["informations"]["path"]
         if "identifiers" in family["informations"]:
@@ -151,16 +175,27 @@ class Examples:  # pylint: disable=no-member,too-few-public-methods
             if dyn_parent is not None and not path.startswith(dyn_parent):
                 continue
             for leader_idx in range(len(leader["example"][path_idx])):
-                followers = {}
+                if self.comment_examples:
+                    followers = CommentedMap()
+                else:
+                    followers = {}
                 for follower in leadership.values():
                     if len(follower["names"]) == 1:
                         name = follower["names"][0]
                     else:
                         name = follower["names"][path_idx]
                     followers[name] = follower["example"][path_idx][leader_idx]
+                    if self.comment_examples and "description" in follower:
+                        description = follower["description"]
+                        if description.endswith('.'):
+                            description = description[:-1]
+                        followers.yaml_add_eol_comment(description, name, column=self.comment_column)
                 examples.append(followers)
                 if leader["mandatory_without_value"]:
-                    followers = {}
+                    if self.comment_examples:
+                        followers = CommentedMap()
+                    else:
+                        followers = {}
                     for follower in leadership.values():
                         if not follower["mandatory_without_value"]:
                             continue
@@ -169,6 +204,11 @@ class Examples:  # pylint: disable=no-member,too-few-public-methods
                         else:
                             name = follower["names"][path_idx]
                         followers[name] = follower["example"][path_idx][leader_idx]
+                        if self.comment_examples and "description" in follower:
+                            description = follower["description"]
+                            if description.endswith('.'):
+                                description = description[:-1]
+                            followers.yaml_add_eol_comment(description, name, column=self.comment_column)
                     examples_mandatories.append(followers)
             break
         return examples, examples_mandatories

tests/results/test_examples_comment/00_0version_underscore.md

@@ -0,0 +1,12 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+version: example              # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+version: example              # A variable
+```

tests/results/test_examples_comment/00_1empty_variable.md

@@ -0,0 +1,12 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+empty: example
+```
+# Example with all variables modifiable
+
+```yaml
+---
+empty: example
+```

tests/results/test_examples_comment/00_2default_calculated.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: no                      # A first variable
+var2:                         # A second variable
+  - no
+```

tests/results/test_examples_comment/00_2default_calculated_multi.md

@@ -0,0 +1,13 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A first variable
+  - no
+  - yes
+  - maybe
+var2:                         # A second variable
+  - no
+  - yes
+  - maybe
+```

tests/results/test_examples_comment/00_2default_calculated_params_permissive.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var2: a_value                 # A second variable
+```

tests/results/test_examples_comment/00_2default_calculated_variable.md

@@ -0,0 +1,16 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1:                         # A first variable
+  - example.net
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A first variable
+  - example.net
+var2:                         # A second variable
+  - example.net
+```

tests/results/test_examples_comment/00_2default_calculated_variable_description.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A first variable
+var2: example                 # A second variable
+```

tests/results/test_examples_comment/00_2default_calculated_variable_description_multi_line.md

@@ -0,0 +1,15 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A first variable
+var3: example                 # A new variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A first variable
+var2: example                 # A second variable
+var3: example                 # A new variable
+```

tests/results/test_examples_comment/00_2default_calculated_variable_transitive.md

@@ -0,0 +1,16 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1:                         # A first variable
+  - example.net
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A first variable
+  - example.net
+var2:                         # A second variable
+  - example.net
+```

tests/results/test_examples_comment/00_4load_subfolder.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A variable
+var2: example                 # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A variable
+var2: example                 # A variable
+```

tests/results/test_examples_comment/00_5load_notype.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+without_type: non             # A variable
+```

tests/results/test_examples_comment/00_6boolean.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: true                    # The first variable
+var2: true                    # The second variable
+var3: true                    # The third variable
+var4: false                   # The forth variable
+var5: false                   # The fifth variable
+var6: false                   # The sixth variable
+```

tests/results/test_examples_comment/00_6boolean_no_mandatory.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: true                # A variable
+```

tests/results/test_examples_comment/00_6choice.md

@@ -0,0 +1,18 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: a_choice                # The first variable
+var2: a_choice                # The second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: a_choice                # The first variable
+var2: a_choice                # The second variable
+var3: a_choice                # The third variable
+var4: a_choice                # The forth variable
+var5: a                       # The fifth variable
+var6: 1                       # The sixth variable
+```

tests/results/test_examples_comment/00_6choice_calculation.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: 9                        # A variable
+```

tests/results/test_examples_comment/00_6choice_link.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: a_choice                # The first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: a_choice                # The first variable
+var2: a_choice                # The second variable
+```

tests/results/test_examples_comment/00_6choice_variable.md

@@ -0,0 +1,10 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A second variable
+  - a
+  - b
+  - c
+var2: a                       # A first variable
+```

tests/results/test_examples_comment/00_6choice_variable_link.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A second variable
+  - a
+  - b
+  - c
+var2: a                       # A first variable
+var3: a                       # A third variable
+```

tests/results/test_examples_comment/00_6choice_variable_link2.md

@@ -0,0 +1,12 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # A second variable
+  - a
+  - b
+  - c
+var2: a                       # A first variable
+family:                       # family
+  var3: a                     # A third variable
+```

tests/results/test_examples_comment/00_6custom.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+custom1: xxx                  # The first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+custom1: xxx                  # The first variable
+custom2: value                # The seconf variable
+```

tests/results/test_examples_comment/00_6domainname.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: my.domain.name      # A domain name variable
+```

tests/results/test_examples_comment/00_6domainname_params.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: my.domain.name      # A domain name variable
+```

tests/results/test_examples_comment/00_6float.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: 0.0                     # The first variable
+var2: 0.0                     # The second variable
+var3: 0.0                     # The third variable
+var4: 10.1                    # The forth variable
+var5: 10.1                    # The fifth variable
+var6: 10.1                    # The sixth variable
+```

tests/results/test_examples_comment/00_6integer.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: 0                       # The first variable
+var2: 0                       # The second variable
+var3: 0                       # The third variable
+var4: 10                      # This forth variable
+var5: 10                      # The fifth variable
+var6: 10                      # The sixth variable
+```

tests/results/test_examples_comment/00_6ip.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: 1.1.1.1                 # An IP
+var2: 192.168.0.128/25        # An IP in CIDR format
+var3: 1.1.1.1/24              # An IP in CIDR format with obsolete CIDR type
+```

tests/results/test_examples_comment/00_6network.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: 1.1.1.0                 # An network
+var2: 1.1.1.0/24              # An network in CIDR format
+var3: 1.1.1.0/24              # An network in CIDR format with obsolete CIDR type
+```

tests/results/test_examples_comment/00_6number.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: 0                       # The first variable
+var2: 0                       # The second variable
+var3: 0                       # The third variable
+var4: 10                      # This forth variable
+var5: 10                      # The fifth variable
+var6: 10                      # The sixth variable
+```

tests/results/test_examples_comment/00_6port.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable1: '111'              # A port variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+variable1: '111'              # A port variable
+variable2: '8080'             # A port variable with default value
+variable3: '8080'             # A port variable with integer default value
+```

tests/results/test_examples_comment/00_6regexp.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: '#b1b1b1'                # A first variable
+```

tests/results/test_examples_comment/00_6regexp_link.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: '#b1b1b1'               # A first variable
+var2: '#b2b1b1'               # A second variable
+```

tests/results/test_examples_comment/00_6secret.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+secret1: secrets              # The first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+secret1: secrets              # The first variable
+secret2: value                # The second variable
+```

tests/results/test_examples_comment/00_6secret_param.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+secret1: secrets              # The first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+secret1: secrets              # The first variable
+secret2: value                # The second variable
+secret3: value                # The third variable
+```

tests/results/test_examples_comment/00_6string.md

@@ -0,0 +1,21 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+var3: example                 # The third variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+var3: example                 # The third variable
+var4: value                   # The forth variable
+var5: value                   # The fifth variable
+var6: value                   # The sixth variable
+var7: '8080'                  # The seventh variable
+var8: 'true'                  # The height variable
+```

tests/results/test_examples_comment/00_7choice_quote.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: quote'                   # A choice
+```

tests/results/test_examples_comment/00_7help.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```

tests/results/test_examples_comment/00_7help_quote.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```

tests/results/test_examples_comment/00_7help_sup.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # The first <variable>
+var2: example                 # The second <variable>
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # The first <variable>
+var2: example                 # The second <variable>
+```

tests/results/test_examples_comment/00_7value_doublequote.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: quote"              # A variable
+```

tests/results/test_examples_comment/00_7value_doublequote2.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: quote'"             # A variable
+```

tests/results/test_examples_comment/00_7value_doublequote3.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: quote\"\'           # A variable
+```

tests/results/test_examples_comment/00_7value_quote.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: quote'              # A variable
+```

tests/results/test_examples_comment/00_8calculation_information.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: example             # A variable
+```

tests/results/test_examples_comment/00_8test.md

@@ -0,0 +1,23 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: test                    # The first variable
+var3: test1                   # The third variable
+var6:                         # The sixth variable
+  - test1
+  - test2
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: test                    # The first variable
+var2: test                    # The second variable
+var3: test1                   # The third variable
+var4:                         # The forth variable
+var5: false                   # The fifth variable
+var6:                         # The sixth variable
+  - test1
+  - test2
+```

tests/results/test_examples_comment/00_9choice_variable_multi.md

@@ -0,0 +1,16 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable1:                    # A first variable
+  - a_choice
+```
+# Example with all variables modifiable
+
+```yaml
+---
+variable1:                    # A first variable
+  - a_choice
+variable2:                    # A second variable
+  - a_choice
+```

tests/results/test_examples_comment/00_9choice_variables.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+source_variable_1: val1       # The first source variable
+source_variable_2: val2       # The second source variable
+my_variable: val1             # A variable
+```

tests/results/test_examples_comment/00_9default_calculation.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: string_1_True_None  # A variable
+```

tests/results/test_examples_comment/00_9default_calculation_information.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: example                  # A variable
+```

tests/results/test_examples_comment/00_9default_calculation_information_other_variable.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A first variable
+var2: example                 # A second variable
+```

tests/results/test_examples_comment/00_9default_calculation_multi_optional.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+my_variable: val1
+my_calculated_variable:
+  - val1
+```

tests/results/test_examples_comment/00_9default_calculation_multi_optional2.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+my_variable: val1
+my_calculated_variable:
+  - val1
+```

tests/results/test_examples_comment/00_9default_calculation_multi_optional_default.md

@@ -0,0 +1,9 @@
+# Example with all variables modifiable
+
+```yaml
+---
+my_variable: val1
+my_calculated_variable:
+  - val1
+  - value
+```

tests/results/test_examples_comment/00_9default_calculation_optional.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+my_calculated_variable:
+  - example
+```
+# Example with all variables modifiable
+
+```yaml
+---
+my_calculated_variable:
+  - example
+```

tests/results/test_examples_comment/00_9default_calculation_optional_exists.md

@@ -0,0 +1,11 @@
+# Example with all variables modifiable
+
+```yaml
+---
+my_variable:
+  - val1
+  - val2
+my_calculated_variable:
+  - val1
+  - val2
+```

tests/results/test_examples_comment/00_9default_calculation_param_optional.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: no                      # A first variable
+var2: no                      # A second variable
+```

tests/results/test_examples_comment/00_9default_information_other_variable.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A first variable
+var2: example                 # A second variable
+```

tests/results/test_examples_comment/00_9default_information_other_variable2.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # A first variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # A first variable
+var2: example                 # A second variable
+```

tests/results/test_examples_comment/00_9default_integer.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: 9                        # A variable
+```

tests/results/test_examples_comment/00_9default_number.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var: 9                        # A variable
+```

tests/results/test_examples_comment/01_6boolean_multi.md

@@ -0,0 +1,21 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # The first variable
+  - true
+var2:                         # The second variable
+  - true
+var3:                         # The third variable
+  - true
+var4:                         # The forth variable
+  - false
+var5:                         # The fifth variable
+  - false
+var6:                         # The sixth variable
+  - false
+var7:                         # The seventh variable
+  - true
+var8:                         # The eighth variable
+  - true
+```

tests/results/test_examples_comment/01_6custom_multi.md

@@ -0,0 +1,16 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+custom1:                      # A first custom variable
+  - xxx
+```
+# Example with all variables modifiable
+
+```yaml
+---
+custom1:                      # A first custom variable
+  - xxx
+custom2:                      # A second custom variable
+  - value
+```

tests/results/test_examples_comment/01_6float_multi.md

@@ -0,0 +1,21 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # The first variable
+  - 0.0
+var2:                         # The second variable
+  - 0.0
+var3:                         # The third variable
+  - 0.0
+var4:                         # The forth variable
+  - 10.1
+var5:                         # The fifth variable
+  - 10.1
+var6:                         # The sixth variable
+  - 10.1
+var7:                         # The seventh variable
+  - 0.0
+var8:                         # The eighth variable
+  - 0.0
+```

tests/results/test_examples_comment/01_6integer_multi.md

@@ -0,0 +1,21 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # The first variable
+  - 0
+var2:                         # The second variable
+  - 0
+var3:                         # The third variable
+  - 0
+var4:                         # The forth variable
+  - 10
+var5:                         # The fifth variable
+  - 10
+var6:                         # The sixth variable
+  - 10
+var7:                         # The seventh variable
+  - 0
+var8:                         # The eighth variable
+  - 0
+```

tests/results/test_examples_comment/01_6integer_multi_mandatory.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var:                          # The first variable
+  - 42
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var:                          # The first variable
+  - 42
+```

tests/results/test_examples_comment/01_6string_empty.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # The second variable
+  - value
+  -
+```

tests/results/test_examples_comment/01_6string_multi.md

@@ -0,0 +1,32 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1:                         # The first variable
+  - example
+var2:                         # The second variable
+  - example
+var3:                         # The third variable
+  - example
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1:                         # The first variable
+  - example
+var2:                         # The second variable
+  - example
+var3:                         # The third variable
+  - example
+var4:                         # The forth variable
+  - value
+var5:                         # The fifth variable
+  - value
+var6:                         # The sixth variable
+  - value
+var7:                         # The seventh variable
+  - value
+var8:                         # The eighth variable
+  - value
+```

tests/results/test_examples_comment/01_7value_multi_doublequote.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable:                     # A variable
+  - quote"
+```

tests/results/test_examples_comment/01_7value_multi_doublequote2.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable:                     # A variable
+  - quote'"
+```

tests/results/test_examples_comment/01_7value_multi_quote.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable:                     # A variable
+  - quote'
+```

tests/results/test_examples_comment/01_8calculation_information_multi.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable:                     # A variable
+  - example
+```

tests/results/test_examples_comment/01_9choice_variable_multi.md

@@ -0,0 +1,16 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable2: a_choice           # A second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+variable1:                    # A first variable
+  - a
+  - b
+  - c
+variable2: a_choice           # A second variable
+```

tests/results/test_examples_comment/01_9choice_variable_optional.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: c                   # A variable
+```

tests/results/test_examples_comment/02_0tags.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: example                 # The first variable
+var2: example                 # The second variable
+```

tests/results/test_examples_comment/04_0type_param.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+int: 10                       # A limited number
+```

tests/results/test_examples_comment/04_0type_param_integer.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+int: 10                       # A limited integer
+```

tests/results/test_examples_comment/04_1auto_save.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+variable: no                  # An auto save variable
+```

tests/results/test_examples_comment/04_1auto_save_and_calculated.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: no                      # A first variable
+var2: no                      # A second variable
+```

tests/results/test_examples_comment/04_1auto_save_and_calculated_hidden.md

@@ -0,0 +1,7 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var1: no                      # A first variable
+var2: yes                     # A second variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var2: example                 # A second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: value                   # A first variable
+var2: example                 # A second variable
+var3: value                   # A third variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden_2.md

@@ -0,0 +1,14 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var2: example                 # A second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: value                   # A first variable
+var2: example                 # A second variable
+var3: example                 # A third variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden_3.md

@@ -0,0 +1,6 @@
+# Example with all variables modifiable
+
+```yaml
+---
+var3: value                   # A third variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden_4.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var2: example                 # A second variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var2: example                 # A second variable
+var3: value                   # A third variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden_5.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var3: example                 # A third variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: value                   # A first variable
+var3: example                 # A third variable
+```

tests/results/test_examples_comment/04_1default_calculation_hidden_6.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+var3: example                 # A third variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+var1: value                   # A first variable
+var3: example                 # A third variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_boolean.md

@@ -0,0 +1,15 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable1: example            # A first variable
+variable2: example            # A seconde variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: no                 # A conditional variable
+variable1: example            # A first variable
+variable2: example            # A seconde variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_optional.md

@@ -0,0 +1,8 @@
+# Example with all variables modifiable
+
+```yaml
+---
+condition: no                 # A condition
+var1: example                 # A first variable
+var2: example                 # A second variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_optional_default.md

@@ -0,0 +1,9 @@
+# Example with all variables modifiable
+
+```yaml
+---
+condition: false              # A condition
+var1: example                 # A first variable
+var3: example                 # A second variable
+var4: example                 # A forth variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: false              # A condition
+variable: example             # A variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable10.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: true               # A condition
+variable: example             # A variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable2.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: true               # A condition
+variable: example             # A variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable3.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: yes                # A condition
+variable: example             # A variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable4.md

@@ -0,0 +1,13 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+condition: yes                # A condition
+variable: example             # A variable
+```

tests/results/test_examples_comment/04_5disabled_calculation_variable5.md

@@ -0,0 +1,12 @@
+# Example with mandatory variables not filled in
+
+```yaml
+---
+variable: example             # A variable
+```
+# Example with all variables modifiable
+
+```yaml
+---
+variable: example             # A variable
+```