feat: personalize mode that we want disable documentation

src/rougail/output_doc/config.py

@@ -87,6 +87,22 @@ doc:
     negative_description: Hide example in documentation
     alternative_name: de
     default: false
+  disabled_modes:
+    description: Disable documentation for variable with those modes
+    multi: true
+    mandatory: false
+    disabled:
+      jinja: |
+        {% if not modes_level %}
+        there is no mode
+        {% endif %}
+      description: disabled when there is no mode available
+    validators:
+      - jinja: |
+          {% if _.disabled_modes not in modes_level %}
+          this mode is not available
+          {% endif %}
+        description: verify if disable modes already exists
   output_format:
     description: Generate document in format
     alternative_name: do

src/rougail/output_doc/doc.py

@@ -18,6 +18,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from warnings import warn
 from typing import Optional
+from itertools import chain
 
 from tiramisu import Calculation, undefined, groups
 from tiramisu.error import ConfigError
@@ -65,14 +66,19 @@ class RougailOutputDoc(Examples):
             rougail.converted.plugins.append("output_doc")
             config = rougail.run()
         self.conf = config
-        self.conf.property.setdefault(frozenset({"advanced"}), "read_write", "append")
+        self.modes_level = rougailconfig["modes_level"]
+        if self.modes_level:
+            self.disabled_modes = rougailconfig["doc.disabled_modes"]
+            if self.disabled_modes:
+                self.conf.property.setdefault(frozenset(self.disabled_modes), "read_write", "append")
+        else:
+            self.disabled_modes = []
         self.conf.property.read_write()
         # self.conf.property.remove("cache")
         self.formater = outputs[output]()
         self.level = rougailconfig["doc.title_level"]
         self.dynamic_paths = {}
         self.with_example = rougailconfig["doc.with_example"]
-        self.modes_level = rougailconfig["modes_level"]
         self.informations = None
         try:
             groups.namespace
@@ -156,8 +162,7 @@ class RougailOutputDoc(Examples):
         do not comment this family
         """
         properties = child.property.get(uncalculated=True)
-        # FIXME advanced is hard coded
-        for hidden_property in ["hidden", "disabled", "advanced"]:
+        for hidden_property in chain(["hidden", "disabled"], self.disabled_modes):
             if hidden_property in properties:
                 return True
         return False

tests/docs/base/12_1auto_save_expert.adoc

@@ -10,3 +10,16 @@ var:
   mode: advanced
   default: no
 ----
+== Variables for "Rougail"
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**rougail.var** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced` `mandatory` `auto modified`            | 
+A variable. +
+**Default**: no               
+|====
+

tests/docs/base/12_1auto_save_expert.json

@@ -1 +1 @@
-{}
+{"rougail": {"type": "namespace", "informations": {"paths": ["rougail"], "names": ["rougail"], "description": "Rougail", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"var": {"type": "variable", "default": "no", "properties": [{"type": "type", "name": "string"}, {"type": "mode", "name": "advanced"}, {"type": "property", "name": "mandatory"}, {"type": "property", "name": "auto modified"}], "paths": ["rougail.var"], "names": ["var"], "descriptions": ["A variable."]}}}}

tests/docs/base/12_1auto_save_expert.md

@@ -13,3 +13,9 @@ var:
   mode: advanced
   default: no
 ```
+# Variables for "Rougail"
+
+| Variable                                                                                                                     | Description                                                                                                                  |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **rougail.var**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced` `mandatory` `auto modified`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | A variable.<br/>**Default**: no                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+

tests/docs/base/12_1auto_save_expert.sh

@@ -9,3 +9,16 @@ var:
   mode: advanced
   default: no
 ```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                                                                                                          Variables for "Rougail"                                                                                                           ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+
+
+                                                                                                       
+  Variable                                           Description                                       
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
+  rougail.var                                                                                          
+  string advanced mandatory auto modified            A variable.                                       
+  Default: no                                                                                          
+                                                                                                       

tests/docs/base/20_0multi_family_expert.adoc

@@ -12,3 +12,23 @@ family:
       description: a variable
       mandatory: false
 ----
+== Variables for "Rougail"
+
+=== a family
+
+`advanced`
+
+==== a sub family
+
+`advanced`
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**rougail.family.subfamily.variable** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced`            | 
+A variable.               
+|====
+

tests/docs/base/20_0multi_family_expert.json

@@ -1 +1 @@
-{}
+{"rougail": {"type": "namespace", "informations": {"paths": ["rougail"], "names": ["rougail"], "description": "Rougail", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"family": {"type": "family", "informations": {"paths": ["rougail.family"], "names": ["family"], "description": "a family", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"subfamily": {"type": "family", "informations": {"paths": ["rougail.family.subfamily"], "names": ["subfamily"], "description": "a sub family", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"variable": {"type": "variable", "properties": [{"type": "type", "name": "string"}, {"type": "mode", "name": "advanced"}], "paths": ["rougail.family.subfamily.variable"], "names": ["variable"], "descriptions": ["A variable."]}}}}}}}}

tests/docs/base/20_0multi_family_expert.md

@@ -15,3 +15,17 @@ family:
       description: a variable
       mandatory: false
 ```
+# Variables for "Rougail"
+
+## a family
+
+`advanced`
+
+### a sub family
+
+`advanced`
+
+| Variable                                                                                         | Description                                                                                      |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **rougail.family.subfamily.variable**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced`                                                                                                                                                                                                                                                                                                                                                                                                        | A variable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+

tests/docs/base/20_0multi_family_expert.sh

@@ -11,3 +11,23 @@ family:
       description: a variable
       mandatory: false
 ```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                                                                                                          Variables for "Rougail"                                                                                                           ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+
+                                                                                                                   a family                                                                                                                   
+
+advanced                                                                                                                                                                                                                                      
+
+                                                                                                                 a sub family                                                                                                                 
+
+advanced                                                                                                                                                                                                                                      
+
+
+                                                                                   
+  Variable                                 Description                             
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
+  rougail.family.subfamily.variable                                                
+  string advanced                          A variable.                             
+                                                                                   

tests/docs/examples/12_1auto_save_expert.md

@@ -13,3 +13,10 @@ var:
   mode: advanced
   default: no
 ```
+# Example with all variables modifiable
+
+```yaml
+---
+rougail:
+  var: no
+```

tests/docs/examples/20_0multi_family_expert.md

@@ -15,3 +15,12 @@ family:
       description: a variable
       mandatory: false
 ```
+# Example with all variables modifiable
+
+```yaml
+---
+rougail:
+  family:
+    subfamily:
+      variable: example
+```

tests/docs/no_namespace/12_1auto_save_expert.adoc

@@ -10,3 +10,16 @@ var:
   mode: advanced
   default: no
 ----
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced` `mandatory` `auto modified`            | 
+A variable. +
+**Default**: no               
+|====
+

tests/docs/no_namespace/12_1auto_save_expert.json

@@ -1 +1 @@
-{}
+{"var": {"type": "variable", "default": "no", "properties": [{"type": "type", "name": "string"}, {"type": "mode", "name": "advanced"}, {"type": "property", "name": "mandatory"}, {"type": "property", "name": "auto modified"}], "paths": ["var"], "names": ["var"], "descriptions": ["A variable."]}}

tests/docs/no_namespace/12_1auto_save_expert.md

@@ -13,3 +13,9 @@ var:
   mode: advanced
   default: no
 ```
+# Variables
+
+| Variable                                                                                                                     | Description                                                                                                                  |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **var**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced` `mandatory` `auto modified`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | A variable.<br/>**Default**: no                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+

tests/docs/no_namespace/12_1auto_save_expert.sh

@@ -9,3 +9,16 @@ var:
   mode: advanced
   default: no
 ```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                                                                                                                 Variables                                                                                                                  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+
+
+                                                                                                       
+  Variable                                           Description                                       
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
+  var                                                                                                  
+  string advanced mandatory auto modified            A variable.                                       
+  Default: no                                                                                          
+                                                                                                       

tests/docs/no_namespace/20_0multi_family_expert.adoc

@@ -12,3 +12,23 @@ family:
       description: a variable
       mandatory: false
 ----
+== Variables
+
+=== a family
+
+`advanced`
+
+==== a sub family
+
+`advanced`
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**family.subfamily.variable** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced`            | 
+A variable.               
+|====
+

tests/docs/no_namespace/20_0multi_family_expert.json

@@ -1 +1 @@
-{}
+{"family": {"type": "family", "informations": {"paths": ["family"], "names": ["family"], "description": "a family", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"subfamily": {"type": "family", "informations": {"paths": ["family.subfamily"], "names": ["subfamily"], "description": "a sub family", "properties": [{"type": "mode", "name": "advanced"}]}, "children": {"variable": {"type": "variable", "properties": [{"type": "type", "name": "string"}, {"type": "mode", "name": "advanced"}], "paths": ["family.subfamily.variable"], "names": ["variable"], "descriptions": ["A variable."]}}}}}}

tests/docs/no_namespace/20_0multi_family_expert.md

@@ -15,3 +15,17 @@ family:
       description: a variable
       mandatory: false
 ```
+# Variables
+
+## a family
+
+`advanced`
+
+### a sub family
+
+`advanced`
+
+| Variable                                                                                         | Description                                                                                      |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **family.subfamily.variable**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced`                                                                                                                                                                                                                                                                                                                                                                                                                | A variable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+

tests/docs/no_namespace/20_0multi_family_expert.sh

@@ -11,3 +11,23 @@ family:
       description: a variable
       mandatory: false
 ```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                                                                                                                 Variables                                                                                                                  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+
+                                                                                                                   a family                                                                                                                   
+
+advanced                                                                                                                                                                                                                                      
+
+                                                                                                                 a sub family                                                                                                                 
+
+advanced                                                                                                                                                                                                                                      
+
+
+                                                                   
+  Variable                         Description                     
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
+  family.subfamily.variable                                        
+  string advanced                  A variable.                     
+                                                                   

tests/mode/00_file.yml

@@ -0,0 +1,22 @@
+---
+version: 1.1
+
+var1:
+  description: my var1
+  mode: basic
+
+var2:
+  description: my var2
+  default:
+    variable: var1
+  mode: standard
+
+var3:
+  description: my var3
+  mode: advanced
+  hidden:
+    jinja: |
+      {% if var1 == 'value' %}
+      it's hidden
+      {% endif %}
+    description: var could be hidden

tests/mode_advanced.adoc

@@ -0,0 +1,18 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var1** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `basic` `mandatory`            | 
+My var1.               
+| 
+
+**var2** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `standard` `mandatory`            | 
+My var2. +
+**Default**: the value of the variable "var1".               
+|====
+

tests/mode_basic.adoc

@@ -0,0 +1,19 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var2** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `standard` `mandatory`            | 
+My var2. +
+**Default**: the value of the variable "var1".               
+| 
+
+**var3** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced` `mandatory` `__hidden__`            | 
+My var3. +
+**Hidden**: var could be hidden.               
+|====
+

tests/mode_basic_advanced.adoc

@@ -0,0 +1,13 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var2** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `standard` `mandatory`            | 
+My var2. +
+**Default**: the value of the variable "var1".               
+|====
+

tests/mode_basic_standard.adoc

@@ -0,0 +1,13 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var3** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced` `mandatory` `__hidden__`            | 
+My var3. +
+**Hidden**: var could be hidden.               
+|====
+

tests/mode_standard.adoc

@@ -0,0 +1,18 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var1** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `basic` `mandatory`            | 
+My var1.               
+| 
+
+**var3** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `advanced` `mandatory` `__hidden__`            | 
+My var3. +
+**Hidden**: var could be hidden.               
+|====
+

tests/mode_standard_advanced.adoc

@@ -0,0 +1,12 @@
+== Variables
+
+[cols="1a,1a"]
+|====
+| Variable   | Description   
+| 
+
+**var1** +
+`https://rougail.readthedocs.io/en/latest/variable.html#variables-types[string]` `basic` `mandatory`            | 
+My var1.               
+|====
+

tests/test_force_optional.py

@@ -3,7 +3,7 @@ from rougail.config import get_rougail_config
 from rougail.output_doc import RougailOutputDoc
 
 
-def test_dictionaries():
+def test_force_optional():
     test_dir = Path(__file__).resolve().parent
     rougailconfig = get_rougail_config(backward_compatibility=False)
     rougailconfig['step.output'] = 'doc'

tests/test_mode.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+from rougail.config import get_rougail_config
+from rougail.output_doc import RougailOutputDoc
+
+
+def _test(modes):
+    test_dir = Path(__file__).resolve().parent
+    rougailconfig = get_rougail_config(backward_compatibility=False)
+    rougailconfig['step.output'] = 'doc'
+#    rougailconfig['tiramisu_cache'] = 'p.py'
+    dirs = [str(test_dir / 'mode')]
+    rougailconfig['modes_level'] = ['basic', 'standard', 'advanced']
+    rougailconfig['main_dictionaries'] = dirs
+    rougailconfig['doc.output_format'] = 'asciidoc'
+    rougailconfig['doc.disabled_modes'] = modes
+    inventory = RougailOutputDoc(rougailconfig=rougailconfig)
+    doc = inventory.gen_doc()
+    result_file = test_dir / f'mode_{"_".join(modes)}.adoc'
+    if not result_file.is_file():
+        with open(str(result_file), 'w') as docfh:
+            docfh.write(doc)
+    with open(str(result_file)) as docfh:
+        result = docfh.read()
+    assert doc == result
+
+
+def test_mode_advanced():
+    _test(['basic', 'standard'])
+
+
+def test_mode_basic_only():
+    _test(['standard', 'advanced'])
+
+
+def test_mode_standard():
+    _test(['basic', 'advanced'])
+
+
+def test_mode_standard_advanced():
+    _test(['basic'])
+
+
+def test_mode_basic_advanced():
+    _test(['standard'])
+
+
+def test_mode_basic_standard():
+    _test(['advanced'])