docs: init synthing & deltachat

docs/nix/scripts/renderOptions.py

@@ -53,11 +53,28 @@ def render_option_header(name: str) -> str:
     return f"# {name}\n"
 
 
-def render_option(name: str, option: dict[str, Any]) -> str:
+def join_lines_with_indentation(lines: list[str], indent: int = 4) -> str:
+    """
+    Joins multiple lines with a specified number of whitespace characters as indentation.
+
+    Args:
+    lines (list of str): The lines of text to join.
+    indent (int): The number of whitespace characters to use as indentation for each line.
+
+    Returns:
+    str: The indented and concatenated string.
+    """
+    # Create the indentation string (e.g., four spaces)
+    indent_str = " " * indent
+    # Join each line with the indentation added at the beginning
+    return "\n".join(indent_str + line for line in lines)
+
+
+def render_option(name: str, option: dict[str, Any], level: int = 2) -> str:
     read_only = option.get("readOnly")
 
     res = f"""
-## {sanitize(name)}
+{"#" * level} {sanitize(name)} {{#{sanitize(name)}}}
 {"Readonly" if read_only else ""}
 {option.get("description", "No description available.")}
 
@@ -74,12 +91,13 @@ def render_option(name: str, option: dict[str, Any]) -> str:
         """
     example = option.get("example", {}).get("text")
     if example:
+        example_indented = join_lines_with_indentation(example.split("\n"))
         res += f"""
 
 ???+ example
 
     ```nix
-    {example}
+{example_indented}
     ```
 """
     if option.get("relatedPackages"):
@@ -100,15 +118,17 @@ def render_option(name: str, option: dict[str, Any]) -> str:
 
 
 def module_header(module_name: str) -> str:
-    return f"""# {module_name}
- 
-To use this module, import it like this:
+    return f"# {module_name}\n"
+
+
+def module_usage(module_name: str) -> str:
+    return f"""To use this module, import it like this:
 
 ```nix
-  {{config, lib, inputs, ...}}: {{
+{{config, lib, inputs, ...}}: {{
     imports = [ inputs.clan-core.clanModules.{module_name} ];
     # ...
-  }}
+}}
 ```
 """
 
@@ -133,7 +153,9 @@ def produce_clan_core_docs() -> None:
             # Create seperate files for nested options
             if len(option_name.split(".")) <= 2:
                 # i.e. clan-core.clanDir
-                output = core_outputs.get(outfile, module_header(module_name))
+                output = core_outputs.get(
+                    outfile, module_header(module_name) + module_usage(module_name)
+                )
                 output += render_option(option_name, info)
                 # Update the content
                 core_outputs[outfile] = output
@@ -182,11 +204,17 @@ def produce_clan_modules_docs() -> None:
             if readme_map.get(module_name, None):
                 output += f"{readme_map[module_name]}\n"
 
+            output += module_usage(module_name)
+
+            output += "\n## Module Options\n"
             for option_name, info in options.items():
-                output += render_option(option_name, info)
+                output += render_option(option_name, info, 3)
 
             outfile = Path(OUT) / f"clanModules/{module_name}.md"
-            outfile.parent.mkdir(parents=True, exist_ok=True)
+            outfile.parent.mkdir(
+                parents=True,
+                exist_ok=True,
+            )
             with open(outfile, "w") as of:
                 of.write(output)
 

docs/site/getting-started/machines.md

@@ -25,7 +25,7 @@ This process involves preparing a suitable hardware and disk partitioning config
          
         2. Boot the target machine and connect it to a network that makes it reachable from your setup computer.
 
-=== "**Cloud Machines**"
+=== "**Baremetal Machines**"
 
     - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
     - [x] **Machine configuration**: See our basic [configuration guide](./configure.md)

docs/site/getting-started/networking.md

@@ -10,7 +10,7 @@ include a new machine into the VPN.
 The VPN controller is initially essential for providing configuration to new
 peers. Once addresses are allocated, the controller's continuous operation is not essential.
 
-### Instructions:
+### Instructions
 
 1. **Designate a Machine**: Label a machine as the VPN controller in the clan,
    referred to as `<CONTROLLER>` henceforth in this guide.
@@ -74,3 +74,22 @@ To introduce a new machine to the VPN, adhere to the following steps:
     The new machine is now part of the VPN, and the ZeroTier
     configuration on NixOS within the Clan project is complete.
 
+## Decision
+
+We chose zerotier because in our tests it was the easiest solution to bootstrap. You can selfhost a controller and the controller doesn't need to be globally reachable.
+
+In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium.
+
+## Specification
+
+By default all machines within one clan are connected via the chosen network technology.
+
+```
+Clan 
+    Node A
+    <-> (zerotier / mycelium / ...) 
+    Node B
+```
+
+If you select multiple network technologies at the same time. e.g. (zerotier + yggdrassil)
+One of them is the primary network and the above statement holds for the primary network.