feat: update tutorial

build.py

@@ -13,11 +13,12 @@ from rougail.user_data_yaml import RougailUserDataYaml
 from rougail.output_doc import RougailOutputDoc
 
 
-PREVIOUS = Path("previous.yml")
 
 
 if __name__ == "__main__":
-    commit_id = sys.argv[1]
+    builder_dir = sys.argv[1]
+    previous = Path(builder_dir) / "previous.yml"
+    commit_id = sys.argv[2]
 #    rougailconfig = RougailConfig.copy()
     rougailconfig = get_rougail_config(backward_compatibility=False, add_extra_options=False)
     rougailconfig['main_structural_directories'] = ['firefox']
@@ -39,10 +40,10 @@ if __name__ == "__main__":
         has_mode = True
     else:
         has_mode = False
+    rougailconfig['step.output'] = 'doc'
     rougail = Rougail(rougailconfig)
     config = rougail.run()
 #    print(config.value.get())
-    rougailconfig['step.output'] = 'doc'
     rougailconfig['doc.output_format'] = 'github'
     rougailconfig['doc.title_level'] = 3
     inventory = RougailOutputDoc(config, rougailconfig=rougailconfig.copy())
@@ -85,42 +86,42 @@ if __name__ == "__main__":
                             doc += file_fh.read()
                         doc += '\n```\n'
     rougailconfig['step.output'] = 'doc'
+    rougailconfig["doc.title_level"] = 4
     inv_doc = inventory.run()[1]
+    CMD = f"foo@bar:~$ git switch --detach {commit_id}\n"
+    CMD += "foo@bar:~$ rougail -m firefox/ "
+    if has_namespace:
+        CMD += "-s Firefox "
+    if has_foxyproxy:
+        CMD += "-xn FoxyProxy -xd 0 foxyproxy/ "
+    if has_mode:
+        CMD += "--modes_level basic standard advanced "
     if file_found and inv_doc:
-        doc += inv_formatter.title('Generated documentation', 3)
+        doc += inv_formatter.title("Let's generate the documentation", 3)
-        CMD = f"foo@bar:~$ git switch --detach {commit_id}\n"
+        cmd = CMD + "-o doc"
-        CMD += "foo@bar:~$ rougail -m firefox/ "
-        if has_namespace:
-            CMD += "-s Firefox "
-        if has_foxyproxy:
-            CMD += "-xn FoxyProxy -xd 0 foxyproxy/ "
-        if has_mode:
-            CMD += "--modes_level basic standard advanced "
-        cmd = CMD + "-o doc -do github"
         doc += f'```console\n{cmd}\n```\n'
         doc += inv_doc
-    if PREVIOUS.is_file():
+    if previous.is_file():
-        rougailconfig["doc.title_level"] = 5
         rougailconfig["doc.contents"] = ["changelog"]
-        rougailconfig["doc.previous_json_file"] = str(PREVIOUS)
+        rougailconfig["doc.previous_json_file"] = str(previous)
     inv_doc = inventory.run()[1]
     if file_found and inv_doc:
-        doc += inv_formatter.title('Changelog', 3)
+        doc += inv_formatter.title("Let's generate the changelog", 3)
-        cmd = CMD + "-o doc --doc.contents variables changelog -do github"
+        cmd = CMD + "-o doc --doc.contents changelog"
         doc += f'```console\n{cmd}\n```\n'
-        doc += inv_doc
+        doc += inv_doc + "\n"
     # save PREVIOUS
     rougailconfig["doc.contents"] = ["variables"]
     rougailconfig['doc.output_format'] = 'json'
     data = inventory.run()[1]
     if data:
-        with PREVIOUS.open('w') as fh:
+        with previous.open('w') as fh:
             dump(loads(data), fh)
     #
     rougailconfig['step.output'] = 'console'
     config = Path('config')
     if config.is_dir():
-        doc += inv_formatter.title('User data', 2)
+        doc += inv_formatter.title('User datas', 2)
         configs = list(config.iterdir())
         configs.sort()
         for idx, dirname in enumerate(configs):
@@ -167,16 +168,15 @@ if __name__ == "__main__":
                         tiramisu_config.property.read_write
                         export = RougailOutputConsole(tiramisu_config,
                                                       rougailconfig=rougailconfig,
-                                                      user_data_errors=data.errors,
+                                                      user_data_errors=errors['errors'],
-                                                      user_data_warnings=data.warnings,
+                                                      user_data_warnings=errors['warnings'],
                                                       )
                         console = export.run()[1]
                         conv = Ansi2HTMLConverter(inline=True)
                         doc += inv_formatter.title('Output in read write mode', 4)
                         cmd = cmd + " --cli.read_write"
                         doc += f"```console\n{cmd}\n```\n"
-                        conv_data = '<pre>' + conv.convert(console, full=False) + "</pre>\n"
+                        doc += '<pre>' + conv.convert(console, full=False) + "</pre>\n"
-                        doc += '<pre>' + conv_data + "</pre>\n"
                         with open(dirname / 'output_rw.html', 'w') as fh_output:
                             fh_output.write(conv_data)
     #

build.sh

@@ -27,7 +27,7 @@ cp "$BUILDER"/firefox.png .
 cp "$BUILDER"/foxyproxy.png .
 cp "$BUILDER"/summary.md .
 touch README.md
-"$BUILDER"/build.py "$VERSION"
+"$BUILDER"/build.py "$BUILDER" "$VERSION"
 rm -rf summary.md
 rm -rf summary_total.md
 rm -rf jinja_caches
@@ -41,7 +41,7 @@ for i in $(ls -d "examples"/* | sort); do
         num=$(echo $(basename "$i"))
         echo "$num"
         commit_id="v${VERSION}_$num"
-        summary="[tutorial $(basename $i)] $(head -n 1 $i/README.md)"
+        summary="[tutorial $commit_id] $(head -n 1 $i/README.md)"
         echo "- [$summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/$commit_id/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/${commit_id}~1..$commit_id))" >> summary_total.md
 done
 
@@ -57,7 +57,7 @@ for i in $(ls -d "examples"/* | sort); do
         num=$(echo $(basename "$i"))
         echo "$num"
         commit_id="v${VERSION}_$num"
-        summary="[tutorial $(basename $i)] $(head -n 1 $i/README.md)"
+        summary="[tutorial $commit_id)] $(head -n 1 $i/README.md)"
         diff_url="https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/${commit_id}~1..$commit_id"
         echo "    - [$summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/$commit_id/README.md) ([diff]($diff_url))" >> summary.md
         cp "summary_total.md" "$DEST"
@@ -100,7 +100,7 @@ for i in $(ls -d "examples"/* | sort); do
         if [ -f config/mode ]; then
             mv config/mode mode
         fi
-        "$BUILDER"/build.py "$commit_id"
+        "$BUILDER"/build.py "$BUILDER" "$commit_id"
         rm -rf config/*/README.md config/read_write config/namespace
         rm -rf jinja_caches summary.md summary_before.md summary_after.md summary_total.md
         if [ -f mode ]; then
@@ -146,6 +146,8 @@ This is what the page looks like:
 echo '# Installation
 
 ```bash
+# git clone -b 1.1 https://forge.cloud.silique.fr/stove/rougail-tutorials.git
+# cd rougail-tutorials
 # python -m venv rougail
 # . rougail/bin/activate
 # pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-data-file

examples/000/README.md

@@ -1 +1 @@
-A structured file with format version
+An empty structured file with format version

examples/000/SUBTITLE.md

@@ -1 +1 @@
-Structural file
+Making a structure file

examples/001/README.md

@@ -0,0 +1 @@
+A first variable with only a name

examples/001/SUBTITLE.md

@@ -0,0 +1 @@
+Let's create our first "variable"

examples/001/config/01/README.md

@@ -0,0 +1 @@
+The user data file is empty. So it's only default value that will be used.

examples/002/README.md

@@ -0,0 +1,9 @@
+Describe the variable
+
+We can add a description to this first variable.
+
+This information is useful for:
+
+- documentation
+- error message
+- help user to known which value to set to this variable (for example with [the user data plugin Questionary](https://forge.cloud.silique.fr/stove/rougail-user-data-questionary)).

examples/003/README.md

@@ -0,0 +1,7 @@
+Set a default value
+
+Now we can define the default value of this variable.
+
+If the user doesn't touch this variable's value, the value is "No proxy"
+
+As user intervention is no more required, so the variable change it's default mode too (from "basic" to "standard").

examples/004/README.md

@@ -1,4 +1,4 @@
-A variable with type "choice"
+Limits the possible values for the variable
 
 "Foo" should not be an option to the "proxy_mode" variable.
 

examples/010/README.md

@@ -1 +1 @@
-A first variable with only a name
+Creating a new family

examples/010/SUBTITLE.md

@@ -1 +1 @@
-Variable: choice the proxy mode
+Group variables inside "families"

examples/010/structural_files/firefox/10-manual.yml

@@ -0,0 +1,8 @@
+%YAML 1.2
+---
+version: 1.1
+
+manual:
+  description: Manual proxy configuration
+  type: family
+...

examples/011/README.md

@@ -1,9 +1,8 @@
-The variable description
+Or a sub family
 
-We can add a description to this first variable.
+Inside a family, we can have variables or families.
 
-This information is useful for:
+The "type" for family "manual" became unecessary because container an other family, so it's not a variable.
+The description can now be has family comment.
 
-- documentation
+In disabled attribute, it's better tu use relative path (we will see the reason in an other slide).
-- error message
-- help user to known which value to set to this variable (for example with [the user data plugin Questionary](https://forge.cloud.silique.fr/stove/rougail-user-data-questionary)).

examples/011/structural_files/firefox/10-manual.yml

@@ -0,0 +1,10 @@
+%YAML 1.2
+---
+version: 1.1
+
+manual:  # Manual proxy configuration
+
+  http_proxy:
+    description: HTTP Proxy
+    type: family
+...

examples/012/README.md

@@ -1,7 +1 @@
-A default value
+Putting a variable inside of a family or a sub family
-
-Now we can define the default value of this variable.
-
-If the user doesn't touch this variable's value, the value is "No proxy"
-
-As user intervention is no more required, so the variable change it's default mode too (from "basic" to "standard").

examples/012/structural_files/firefox/10-manual.yml

@@ -6,7 +6,5 @@ manual:  # Manual proxy configuration
 
   http_proxy:  # HTTP Proxy
 
-    address:
+    address:  # HTTP address
-      description: HTTP address
-      type: domainname
 ...

examples/013/structural_files/firefox/00-proxy.yml

@@ -1,15 +0,0 @@
-%YAML 1.2
----
-version: 1.1
-
-proxy_mode:
-  description: Configure Proxy Access to the Internet
-  type: choice
-  choices:
-    - No proxy
-    - Auto-detect proxy settings for this network
-    - Use system proxy settings
-    - Manual proxy configuration
-    - Automatic proxy configuration URL
-  default: No proxy
-...

examples/014/README.md

@@ -1,3 +0,0 @@
-Choice type is optional
-
-The type is optional in choice type (if we have choices attributes, it's a choice option).

examples/014/config

@@ -1 +0,0 @@
-../010/config

examples/020/README.md

@@ -1,14 +1 @@
-A family
+A variable with type "domainname"
-
-The "manual" mode structural descriptions are write in a new files to separate things. But Rougail will concatenate variables and families.
-
-We create a family, which will contain other variables.
-
-This family has:
-
-- a description
-- a type
-
-As there is no variable inside this family, the type is mandatory. Without it, Rougail will create a variable.
-
-In fact, this family will be deleted by Rougail too because it is empty.

examples/020/SUBTITLE.md

@@ -1 +0,0 @@
-Family: proxy manual

examples/020/TITLE.md

@@ -0,0 +1 @@
+Constrainte the value of a variable with it's type

examples/020/structural_files/firefox/10-manual.yml

@@ -2,7 +2,11 @@
 ---
 version: 1.1
 
-manual:
+manual:  # Manual proxy configuration
-  description: Manual proxy configuration
+
-  type: family
+  http_proxy:  # HTTP Proxy
+
+    address:
+      description: HTTP address
+      type: domainname
 ...

examples/021/README.md

@@ -1,8 +1 @@
-A sub family
+A variable with type's parameters
-
-Inside a family, we can have variables or families.
-
-The "type" for family "manual" became unecessary because container an other family, so it's not a variable.
-The description can now be has family comment.
-
-In disabled attribute, it's better tu use relative path (we will see the reason in an other slide).

examples/021/structural_files/firefox/10-manual.yml

@@ -4,7 +4,11 @@ version: 1.1
 
 manual:  # Manual proxy configuration
 
-  http_proxy:
+  http_proxy:  # HTTP Proxy
-    description: HTTP Proxy
+
-    type: family
+    address:
+      description: HTTP address
+      type: domainname
+      params:
+        allow_ip: true
 ...

examples/022/README.md

@@ -1 +1 @@
-A variable inside sub family
+A variable with type "port"

examples/022/structural_files/firefox/10-manual.yml

@@ -6,5 +6,14 @@ manual:  # Manual proxy configuration
 
   http_proxy:  # HTTP Proxy
 
-    address:  # HTTP address
+    address:
+      description: HTTP address
+      type: domainname
+      params:
+        allow_ip: true
+
+    port:
+      description: HTTP Port
+      type: port
+      default: 8080
 ...

examples/023/README.md

@@ -1 +1 @@
-A variable with type "domainname"
+A variable with type "boolean"

examples/023/SUBTITLE.md

@@ -1 +0,0 @@
-Variable: type and type parameters

examples/023/TITLE.md

@@ -1 +0,0 @@
-HTTP Manual mode

examples/024/README.md

@@ -1 +1 @@
-A variable with type's parameters
+Copy HTTP manual proxy to HTTPS manual proxy

examples/024/config

@@ -1 +1 @@
-../022/config
+../013/config

examples/024/structural_files/firefox/10-manual.yml

@@ -1,14 +0,0 @@
-%YAML 1.2
----
-version: 1.1
-
-manual:  # Manual proxy configuration
-
-  http_proxy:  # HTTP Proxy
-
-    address:
-      description: HTTP address
-      type: domainname
-      params:
-        allow_ip: true
-...

examples/025/README.md

@@ -1 +0,0 @@
-A variable with type "port"

examples/025/structural_files/firefox/10-manual.yml

@@ -1,19 +0,0 @@
-%YAML 1.2
----
-version: 1.1
-
-manual:  # Manual proxy configuration
-
-  http_proxy:  # HTTP Proxy
-
-    address:
-      description: HTTP address
-      type: domainname
-      params:
-        allow_ip: true
-
-    port:
-      description: HTTP Port
-      type: port
-      default: 8080
-...

examples/026/README.md

@@ -1 +0,0 @@
-A disabled family

examples/026/SUBTITLE.md

@@ -1 +0,0 @@
-Property: disabled

examples/027/README.md

@@ -1 +0,0 @@
-A conditional disabled family with a variable

examples/027/config

@@ -1 +0,0 @@
-../022/config

examples/030/README.md

@@ -1 +1 @@
-A variable with type "boolean"
+A disabled family

examples/030/SUBTITLE.md

@@ -0,0 +1 @@
+Disable a family

examples/030/TITLE.md

@@ -1 +1 @@
-HTTP proxy provides HTTPS proxy
+Define access to variable or family

examples/030/config

@@ -1 +1 @@
-../013/config
+../022/config

examples/031/README.md

@@ -1 +1 @@
-Copy HTTP manual proxy to HTTPS manual proxy
+A conditional disabled family with a variable

examples/031/TITLE.md

@@ -1 +0,0 @@
-HTTPS Manual mode

examples/031/config

@@ -1 +1 @@
-../013/config
+../022/config

examples/034/README.md

@@ -1 +0,0 @@
-A calculated default value

examples/034/SUBTITLE.md

@@ -1 +0,0 @@
-Variable: calculated default value

examples/034/structural_files/firefox/20-manual.yml

@@ -1,27 +0,0 @@
-%YAML 1.2
----
-version: 1.1
-
-manual:
-
-  use_for_https: true  # Also use this proxy for HTTPS
-
-  https_proxy:
-    description: HTTPS Proxy
-    hidden:
-      variable: _.use_for_https
-
-    address:
-      description: HTTPS address
-      type: domainname
-      params:
-        allow_ip: true
-      default:
-        variable: __.http_proxy.address
-
-    port:
-      description: HTTPS Port
-      type: port
-      default:
-        variable: __.http_proxy.port
-...

examples/035/README.md

@@ -1 +0,0 @@
-Variable type and parameters type are copied with default value

examples/035/config

@@ -1 +0,0 @@
-../017/config

examples/040/README.md

@@ -1 +1 @@
-Family: a dynamic family
+A calculated default value

examples/040/TITLE.md

@@ -1 +1 @@
-SOCKS Manual mode
+Variable: calculated default value

examples/040/config

@@ -1 +1 @@
-../018/config
+../013/config