yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request 'Refactor(docs): consistent structure across references & fix broken cli links' (#3724) from hsjobeki/clan-core:docs-3 into main

Browse Source 
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/3724
This commit is contained in:
hsjobeki
2025-05-21 07:23:16 +00:00
parent afddcd2186 2ba110d354
commit f470ebce1a
16 changed files with 70 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/mkdocs.yml
View File

@@ -81,14 +81,14 @@ nav:
- Reference:
- Overview: reference/index.md
- Clan Services:
- reference/clanServices/index.md
- Overview: reference/clanServices/index.md
- reference/clanServices/admin.md
- reference/clanServices/hello-world.md
- reference/clanServices/wifi.md
- Clan Modules:
- Overview:
- reference/clanModules/index.md
- reference/clanModules/frontmatter/index.md
- Overview: reference/clanModules/index.md
- Frontmatter Format: reference/clanModules/frontmatter/index.md
- reference/clanModules/frontmatter/index.md
# TODO: display the docs of the clan.service modules
- reference/clanModules/admin.md
# This is the module overview and should stay at the top
@@ -132,7 +132,7 @@ nav:
- reference/clanModules/zerotier.md
- reference/clanModules/zt-tcp-relay.md
- CLI:
- reference/cli/index.md
- Overview: reference/cli/index.md
- reference/cli/backups.md
- reference/cli/facts.md
@@ -146,17 +146,18 @@ nav:
- reference/cli/state.md
- reference/cli/vars.md
- reference/cli/vms.md
- Clan Core:
- reference/clan-core/index.md
- NixOS Modules:
- clan.core:
- Overview: reference/clan.core/index.md
- reference/clan-core/backups.md
- reference/clan-core/deployment.md
- reference/clan-core/facts.md
- reference/clan-core/networking.md
- reference/clan-core/settings.md
- reference/clan-core/sops.md
- reference/clan-core/state.md
- reference/clan-core/vars.md
- reference/clan.core/backups.md
- reference/clan.core/deployment.md
- reference/clan.core/facts.md
- reference/clan.core/networking.md
- reference/clan.core/settings.md
- reference/clan.core/sops.md
- reference/clan.core/state.md
- reference/clan.core/vars.md
- Nix API:
- buildClan: reference/nix-api/buildclan.md
- Inventory: reference/nix-api/inventory.md

28
docs/nix/render_options/__init__.py
View File

@@ -206,7 +206,12 @@ Some modules are considered 'low-level' or 'expert modules' and are not availabl
"""
clan_core_descr = """`clan.core` is always included in each machine `config`.
clan_core_descr = """
`clan.core` is always present in a clan machine
* It is a module of class **`nixos`**
* Provides a set of common options for every machine (in addition to the NixOS options)
Your can customize your machines behavior with the configuration [options](#module-options) provided below.
"""
@@ -292,16 +297,28 @@ def produce_clan_core_docs() -> None:
core_outputs: dict[str, str] = {}
with CLAN_CORE_DOCS.open() as f:
options: dict[str, dict[str, Any]] = json.load(f)
module_name = "clan-core"
module_name = "clan.core"
transform = {n.replace("clan.core.", ""): v for n, v in options.items()}
split = split_options_by_root(transform)
# Prepopulate the index file header
indexfile = f"{module_name}/index.md"
core_outputs[indexfile] = (
module_header(module_name) + clan_core_descr + options_head
)
core_outputs[indexfile] = module_header(module_name) + clan_core_descr
core_outputs[indexfile] += """!!! info "Submodules"\n"""
for submodule_name, split_options in split.items():
root = options_to_tree(split_options, debug=True)
module = root.suboptions[0]
module_type = module.info.get("type")
if module_type is not None and "submodule" not in module_type:
continue
core_outputs[indexfile] += (
f" - [{submodule_name}](./{submodule_name}.md)\n"
)
core_outputs[indexfile] += options_head
for submodule_name, split_options in split.items():
outfile = f"{module_name}/{submodule_name}.md"
@@ -317,7 +334,6 @@ def produce_clan_core_docs() -> None:
print("type", module.info.get("type"))
module_type = module.info.get("type")
if module_type is not None and "submodule" not in module_type:
outfile = indexfile
init_level = 2

2
docs/site/guides/getting-started/secrets.md
View File

@@ -3,7 +3,7 @@ Clan enables encryption of secrets (such as passwords & keys) ensuring security
By default, Clan uses the [sops](https://github.com/getsops/sops) format
and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
Clan can also be configured to be used with other secret store [backends](https://docs.clan.lol/reference/clan-core/vars/#clan.core.vars.settings.secretStore).
Clan can also be configured to be used with other secret store [backends](../../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
This guide will walk you through:

2
docs/site/guides/migrations/migration-facts-vars.md
View File

@@ -5,7 +5,7 @@ For a high level overview about `vars` see our [blog post](https://clan.lol/blog
This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend
to the [`vars`](../../guides/vars-backend.md) backend.
The `vars` [module](../../reference/clan-core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
## Keep Existing Values

4
docs/site/guides/vars-backend.md
View File

@@ -7,7 +7,7 @@ Defining a linux user's password via the nixos configuration previously required
In this example, we will guide you through automating that interaction using clan `vars`.
For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](https://docs.clan.lol/reference/clan-core/vars/)
For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
This guide assumes
- clan is set up already (see [Getting Started](../guides/getting-started/index.md))
@@ -147,5 +147,5 @@ Updated var root-password/password-hash
## Further Reading
- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan-core/vars.md)
- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan.core/vars.md)
- [Reference Documentation for the `clan vars` cli command](../reference/cli/vars.md)

2
docs/site/index.md
View File

@@ -70,7 +70,7 @@ hide:
An overview of available service modules
- [Core](./reference/clan-core/index.md)
- [Core](./reference/clan.core/index.md)
---

2
docs/site/reference/index.md
View File

@@ -6,7 +6,7 @@ This section of the site provides an overview of available options and commands
- Learn how to use the [Clan CLI](./cli/index.md)
- Explore available services and application [modules](./clanModules/index.md)
- Discover [configuration options](./clan-core/index.md) that manage essential features
- Discover [configuration options](./clan.core/index.md) that manage essential features
- Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan
---

20
pkgs/clan-cli/clan_cli/__init__.py
View File

@@ -119,7 +119,7 @@ def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
description="The clan cli tool",
epilog=(
f"""
Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli/")}
Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli")}
For more detailed information, visit: {help_hyperlink("docs", "https://docs.clan.lol")}
"""
),
@@ -171,7 +171,7 @@ Examples:
The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
with the name [NAME].
For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/getting-started/backups")}.
For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -190,7 +190,7 @@ Examples:
Will create a new clan flake in the specified directory and create it if it
doesn't exist yet. The flake will be created from a default template.
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started")}
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -208,7 +208,7 @@ Examples:
$ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started/installer")}
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -235,7 +235,7 @@ Examples:
the json string. [JSON] can either be a json formatted string itself, or point
towards a file containing the deployment information
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -259,7 +259,7 @@ Examples:
$ clan secrets get [SECRET]
Will display the content of the specified secret.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -296,7 +296,7 @@ Examples:
This is especially useful for resetting certain passwords while leaving the rest
of the facts for a machine in place.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -334,7 +334,7 @@ Examples:
This is especially useful for resetting certain passwords while leaving the rest
of the vars for a machine in place.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -364,7 +364,7 @@ Examples:
If the `--target-host` flag is omitted will try to find host information by
checking the deployment configuration inside the specified machine.
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -427,7 +427,7 @@ Examples:
$ clan state list [MACHINE]
List state of the machines managed by Clan.
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/backups")}
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,

8
pkgs/clan-cli/clan_cli/facts/cli.py
View File

@@ -31,7 +31,7 @@ Examples:
Will check facts for the specified machine.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -61,7 +61,7 @@ Examples:
Will list facts for the specified machine.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -101,7 +101,7 @@ Examples:
This is especially useful for resetting certain passwords while leaving the rest
of the facts for a machine in place.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -125,7 +125,7 @@ Examples:
$ clan facts upload [MACHINE]
Will upload secrets to a specific machine.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,

3
pkgs/clan-cli/clan_cli/hyperlink.py
View File

@@ -37,4 +37,7 @@ def docs_hyperlink(description: str, url: str) -> str:
"""
Returns a markdown hyperlink
"""
url = url.replace("https://docs.clan.lol", "../..")
url = url.replace("index.html", "index")
url += ".md"
return f"[{description}]({url})"

8
pkgs/clan-cli/clan_cli/machines/cli.py
View File

@@ -37,7 +37,7 @@ Examples:
To exclude machines being updated `clan.deployment.requireExplicitUpdate = true;`
can be set in the machine config.
For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
"""
),
formatter_class=argparse.RawTextHelpFormatter,
@@ -93,7 +93,7 @@ Examples:
$ clan machines update-hardware-config [MACHINE] [TARGET_HOST]
Will generate hardware specifics for the the specified `[TARGET_HOST]` and place the result in hardware.nix for the given machine `[MACHINE]`.
For more detailed information, visit: https://docs.clan.lol/getting-started/configure/#machine-configuration
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration
"""
),
@@ -123,8 +123,8 @@ Examples:
Will install the specified machine [MACHINE] to the host exposed by
the deployment information of the [JSON] deployment string.
For information on how to set up the installer see: https://docs.clan.lol/getting-started/installer/
For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/installer/
For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
"""
),
formatter_class=argparse.RawTextHelpFormatter,

2
pkgs/clan-cli/clan_cli/machines/machines.py
View File

@@ -93,7 +93,7 @@ class Machine:
msg = f"'targetHost' is not set for machine '{self.name}'"
raise ClanError(
msg,
description="See https://docs.clan.lol/getting-started/deploy/#setting-the-target-host for more information.",
description="See https://docs.clan.lol/guides/getting-started/deploy/#setting-the-target-host for more information.",
)
return val

2
pkgs/clan-cli/clan_cli/state/__init__.py
View File

@@ -29,7 +29,7 @@ def register_parser(parser: argparse.ArgumentParser) -> None:
List state of the machine [MACHINE] managed by Clan.
For more detailed information, visit: https://docs.clan.lol/getting-started/backups/
For more detailed information, visit: https://docs.clan.lol/guides/backups
"""
),
formatter_class=argparse.RawTextHelpFormatter,

2
pkgs/clan-cli/clan_cli/vars/cli.py
View File

@@ -197,7 +197,7 @@ Examples:
$ clan vars upload [MACHINE]
Will upload secrets to a specific machine.
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
"""
),
formatter_class=argparse.RawTextHelpFormatter,

2
templates/clan/flake-parts/flake.nix
View File

@@ -19,7 +19,7 @@
"aarch64-darwin"
];
imports = [ inputs.clan-core.flakeModules.default ];
# https://docs.clan.lol/getting-started/flake-parts/
# https://docs.clan.lol/guides/getting-started/flake-parts/
clan = {
meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.

2
templates/clan/new-clan/flake.nix
View File

@@ -14,7 +14,7 @@
# All machines in ./machines will be imported.
# Prerequisite: boot into the installer.
# See: https://docs.clan.lol/getting-started/installer
# See: https://docs.clan.lol/guides/getting-started/installer
# local> mkdir -p ./machines/machine1
# local> Edit ./machines/<machine>/configuration.nix to your liking.
machines = {