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
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 = {

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

@@ -77,7 +77,7 @@ This process involves preparing a suitable hardware and disk partitioning config
│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │
│ │Multicast DNS: nixos-installer.local │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ Press 'Ctrl-C' for console access │
│ Press 'Ctrl-C' for console access │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
@@ -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.
---

111
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.
- :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__
```bash
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
```
---
=== "**NixOS**"
Create your own clan and get everything
running in a couple of minutes.
If you run NixOS the `nix` binary is already installed.
[:octicons-arrow-right-24: Getting started](./getting-started/index.md)
You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
- :material-sign-direction:{ .lg .middle } __Manual__
```nix
{ nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
```
---
=== "**Other**"
Instructions and explanations for practical Implementations ordered by Topic.
Clan doesn't offer dedicated support for other operating systems yet.
[:octicons-arrow-right-24: Manual](./manual/index.md)
### Step 1: Add Clan CLI to Your Shell
- :material-api:{ .lg .middle } __Reference__
Add the Clan CLI into your development workflow:
---
```bash
nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
```
Detailed Specification of Functions and APIs.
You can find reference documentation for the `clan` cli program [here](./reference/cli/index.md).
[:octicons-arrow-right-24: Reference](./reference/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**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick.
---
</div>

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

33
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.
- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!
- [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!

18
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
- 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'
```