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

Docs: add top-level index, refactor according to diataxis

Browse Source
This commit is contained in:
Johannes Kirschbauer
2024-09-22 18:38:14 +02:00
parent 25ec3308d1
commit 8e7e346b28
11 changed files with 207 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
clanModules/syncthing/README.md
View File

@@ -19,7 +19,7 @@ We recommend configuring this module as an sync-service through the provided opt
- **Share Folders**: Select folders to share with connected devices and configure permissions and synchronization parameters.
!!! info
Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clan.syncthing.introducer)
Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clansyncthingintroducer)
If that is not the case you can add the other device by its Device ID manually.
You can find and share Device IDs under the "Add Device" button in the Web GUI. (`127.0.0.1:8384`)

10
docs/mkdocs.yml
View File

@@ -39,8 +39,12 @@ exclude_docs: |
/drafts/
nav:
- Get Started:
- index.md
- Manual:
- Overview: manual/index.md
- Tutorials:
- Getting Started:
- getting-started/index.md
- Installer: getting-started/installer.md
- Configure: getting-started/configure.md
- Secrets & Facts: getting-started/secrets.md
@@ -49,14 +53,12 @@ nav:
- Mesh VPN: getting-started/mesh-vpn.md
- Backup & Restore: getting-started/backups.md
- Flake-parts: getting-started/flake-parts.md
- Manual:
- Overview: manual/index.md
- Include Machines: manual/include-machines.md
- Inventory: manual/inventory.md
- Secrets: manual/secrets.md
- Secure Boot: manual/secure-boot.md
- Contribute: manual/contribute.md
- Options:
- Reference:
- Overview: reference/index.md
- Clan Modules:
- reference/clanModules/index.md

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

@@ -144,9 +144,8 @@ To use this module, import it like th:
"""
clan_core_descr = """ClanCore delivers all the essential features for every clan.
It's always included in your setup, and you can customize your clan's behavior with the configuration [options](#module-options) provided below.
clan_core_descr = """`clan.core` is always included in each machine `config`.
Your can customize your machines behavior with the configuration [options](#module-options) provided below.
"""
options_head = "\n## Module Options\n"

2
docs/site/getting-started/configure.md
View File

@@ -52,7 +52,7 @@ In the `flake.nix` file:
=== "**template using flake-parts**"
!!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts."
!!! info "See [Clan with flake-parts](../manual/flake-parts.md) for help migrating to flake-parts."
```nix title="flake.nix" hl_lines="3"
clan = {

2
docs/site/getting-started/deploy.md
View File

@@ -100,7 +100,7 @@ This process involves preparing a suitable hardware and disk partitioning config
```
2. The root password for the installer medium.
This password is autogenerated and meant to be easily typeable.
3. See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi).
3. See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi-manually).
4. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
text__, images, ... basically anything that can be written in Markdown.

109
docs/site/getting-started/index.md Normal file
View File

@@ -0,0 +1,109 @@
# Getting Started
Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository!
### Prerequisites
=== "**Linux**"
Clan depends on nix installed on your system. Run the following command to install nix.
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
If you already have installed Nix, make sure you have the `nix-command` and `flakes` configuration enabled in your ~/.config/nix/nix.conf.
The determinate installer already comes with this configuration by default.
```bash
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
```
=== "**NixOS**"
If you run NixOS the `nix` binary is already installed.
You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
```nix
{ nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
```
=== "**Other**"
Clan doesn't offer dedicated support for other operating systems yet.
### Step 1: Add Clan CLI to Your Shell
Add the Clan CLI into your development workflow:
```bash
nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
```
You can find reference documentation for the `clan` cli program [here](../reference/cli/index.md).
Alternatively you can check out the help pages directly:
```terminalSession
clan --help
```
### Step 2: Initialize Your Project
Set the foundation of your Clan project by initializing it as follows:
```bash
clan flakes create my-clan
```
This command creates the `flake.nix` and `.clan-flake` files for your project.
It will also generate files from a default template, to help show general clan usage patterns.
### Step 3: Verify the Project Structure
Ensure that all project files exist by running:
```bash
cd my-clan
tree
```
This should yield the following:
``` { .console .no-copy }
.
├── flake.nix
├── machines
│   ├── jon
│   │   ├── configuration.nix
│   │   └── hardware-configuration.nix
│   └── sara
│   ├── configuration.nix
│   └── hardware-configuration.nix
└── modules
└── shared.nix
5 directories, 9 files
```
```bash
clan machines list
```
``` { .console .no-copy }
jon
sara
```
!!! success
You just successfully bootstrapped your first clan directory.
---
### What's Next?
- [**Installer**](./installer.md): Setting up new computers remotely is easy with an USB stick.
---

123
docs/site/index.md
View File

@@ -1,109 +1,38 @@
# Setup
# Home
Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository!
## Welcome to **Clan**'s documentation
### Prerequisites
[Quickstart Guide](./getting-started/index.md){ .md-button }
=== "**Linux**"
## What's inside
Clan depends on nix installed on your system. Run the following command to install nix.
This documentation is structured into the following sections
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
<div class="grid cards" markdown>
If you already have installed Nix, make sure you have the `nix-command` and `flakes` configuration enabled in your ~/.config/nix/nix.conf.
The determinate installer already comes with this configuration by default.
```bash
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
```
=== "**NixOS**"
If you run NixOS the `nix` binary is already installed.
You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
```nix
{ nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
```
=== "**Other**"
Clan doesn't offer dedicated support for other operating systems yet.
### Step 1: Add Clan CLI to Your Shell
Add the Clan CLI into your development workflow:
```bash
nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
```
You can find reference documentation for the `clan` cli program [here](./reference/cli/index.md).
Alternatively you can check out the help pages directly:
```terminalSession
clan --help
```
### Step 2: Initialize Your Project
Set the foundation of your Clan project by initializing it as follows:
```bash
clan flakes create my-clan
```
This command creates the `flake.nix` and `.clan-flake` files for your project.
It will also generate files from a default template, to help show general clan usage patterns.
### Step 3: Verify the Project Structure
Ensure that all project files exist by running:
```bash
cd my-clan
tree
```
This should yield the following:
``` { .console .no-copy }
.
├── flake.nix
├── machines
│   ├── jon
│   │   ├── configuration.nix
│   │   └── hardware-configuration.nix
│   └── sara
│   ├── configuration.nix
│   └── hardware-configuration.nix
└── modules
└── shared.nix
5 directories, 9 files
```
```bash
clan machines list
```
``` { .console .no-copy }
jon
sara
```
!!! success
You just successfully bootstrapped your first clan directory.
- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__
---
### What's Next?
Create your own clan and get everything
running in a couple of minutes.
- [**Installer**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick.
[:octicons-arrow-right-24: Getting started](./getting-started/index.md)
- :material-sign-direction:{ .lg .middle } __Manual__
---
Instructions and explanations for practical Implementations ordered by Topic.
[:octicons-arrow-right-24: Manual](./manual/index.md)
- :material-api:{ .lg .middle } __Reference__
---
Detailed Specification of Functions and APIs.
[:octicons-arrow-right-24: Reference](./reference/index.md)
</div>

0
docs/site/getting-started/flake-parts.md → docs/site/manual/flake-parts.md
View File

31
docs/site/manual/index.md
View File

@@ -1,11 +1,34 @@
# Manual
# :material-book: Manual
Explore the Clan Framework in detail with comprehensive information on specific topics:
Instructions and explanations for practical Implementations ordered by Topics.
## Tutorials
**Learning-oriented adventures with a hands-on experience.**
<div class="grid cards" markdown>
- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__
---
Create your own clan and get everything
running in minutes
[:octicons-arrow-right-24: Getting started](../getting-started/index.md)
</div>
## Guides
**How-to Guides for achieving a certain goal or solving a specific issue.**
- [Include Machines](./include-machines.md): Learn how Clan automatically includes machines and Nix files.
- [Secrets](./secrets.md): Learn how you can manage secrets
- [Secrets](./secrets.md): Learn how to manage secrets.
- [Inventory](./inventory.md): Access a distributed and editable version of the NixOS module system.
- [Inventory](./inventory.md): Distributed and editable version of the NixOS module system.
- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/).
- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!

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

@@ -1,6 +1,20 @@
This section of the site provides an automatically generated overview of the available options and commands within the Clan Framework.
# :material-api: Overview
This section of the site provides an **automatically extracted** overview of the available options and commands within the Clan Framework.
---
- 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
- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan
---
!!! Note
This documentation is always built for the main branch.
If you need documentation for a specific commit you can build it on your own
```bash
nix build 'git+https://git.clan.lol/clan/clan-core?ref=0324f4d4b87d932163f351e53b23b0b17f2b5e15#docs'
```

16
lib/build-clan/interface.nix
View File

@@ -8,7 +8,21 @@ in
directory = lib.mkOption {
type = types.path;
default = self;
description = "The directory containing the clan subdirectory";
defaultText = "Root directory of the flake";
description = ''
The directory containing the clan.
A typical directory structure could look like this:
```
.
├── flake.nix
├── assets
├── machines
├── modules
└── sops
```
'';
};
specialArgs = lib.mkOption {