From 3a0dfc8919e92f0377908d76f11d6627d91a3740 Mon Sep 17 00:00:00 2001
From: Olivier 'reivilibre <olivier@librepush.net>
Date: Wed, 6 Dec 2023 00:09:28 +0000
Subject: [PATCH] Add a basic docs book

---
 book.toml               | 19 ++++++++++++
 docs/SUMMARY.md         | 13 ++++++++
 docs/admin/cli/index.md |  1 +
 docs/admin/cli/serve.md |  1 +
 docs/admin/cli/user.md  | 67 +++++++++++++++++++++++++++++++++++++++++
 docs/admin/install.md   |  1 +
 docs/index.md           |  3 ++
 flake.nix               |  1 +
 8 files changed, 106 insertions(+)
 create mode 100644 book.toml
 create mode 100644 docs/SUMMARY.md
 create mode 100644 docs/admin/cli/index.md
 create mode 100644 docs/admin/cli/serve.md
 create mode 100644 docs/admin/cli/user.md
 create mode 100644 docs/admin/install.md
 create mode 100644 docs/index.md

diff --git a/book.toml b/book.toml
new file mode 100644
index 0000000..7c43016
--- /dev/null
+++ b/book.toml
@@ -0,0 +1,19 @@
+[book]
+authors = ["Olivier"]
+language = "en"
+multilingual = false
+src = "docs"
+title = "idCoop Documentation"
+description = "Documentation for idCoop (a small identity provider)"
+
+[output.html]
+default-theme = "rust"
+git-repository-url = "https://git.emunest.net/reivilibre/idcoop"
+git-repository-icon = "fa-git-alt"
+fold = { enable = false }
+
+# TODO toml highlighting
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
new file mode 100644
index 0000000..23f6caf
--- /dev/null
+++ b/docs/SUMMARY.md
@@ -0,0 +1,13 @@
+[Introduction](index.md)
+
+# Administration
+
+- [Installation](admin/install.md)
+- [Command Line Tool](admin/cli/index.md)
+    - [serve](admin/cli/serve.md)
+    - [user](admin/cli/user.md)
+
+
+# Development
+
+
diff --git a/docs/admin/cli/index.md b/docs/admin/cli/index.md
new file mode 100644
index 0000000..bcb7198
--- /dev/null
+++ b/docs/admin/cli/index.md
@@ -0,0 +1 @@
+# Command Line Tool
diff --git a/docs/admin/cli/serve.md b/docs/admin/cli/serve.md
new file mode 100644
index 0000000..5293e3f
--- /dev/null
+++ b/docs/admin/cli/serve.md
@@ -0,0 +1 @@
+# serve
diff --git a/docs/admin/cli/user.md b/docs/admin/cli/user.md
new file mode 100644
index 0000000..b3ba59e
--- /dev/null
+++ b/docs/admin/cli/user.md
@@ -0,0 +1,67 @@
+# `idcoop user` — user management commands
+
+<!-- toc -->
+
+## `idcoop user add` — create a user
+
+Creates a user but does not set a password for the user. Optionally, the user can be locked.
+
+```
+idcoop user add [--locked] <USERNAME>
+```
+aliases: `idcoop user new`, `idcoop user create`
+
+- `<USERNAME>`: name of the user being added
+- `--locked`: specify if the user should be locked when created. Default is to not lock the user.
+
+
+## `idcoop user delete` — delete a user
+
+Deletes a user entirely from the database.
+
+**WARNING**: Deleting a user makes its name available for re-use, which can be undesirable.
+Further, the user won't be deregistered from any applications that use idCoop as their identity provider.
+Consider whether this is what you really want before continuing.
+[Locking the user may be a better fit in many cases.](#idcoop-user-lock-idcoop-user-unlock--lock-or-unlock-a-user)
+
+```
+idcoop user delete <USERNAME>
+```
+aliases: `idcoop user rm`, `idcoop user remove`, `idcoop user del`
+
+- `<USERNAME>`: name of the user to be deleted
+
+
+## `idcoop user change-password` — change a user's password
+
+Changes the specified user's password to a new one which is prompted for.
+
+```
+idcoop user change-password <USERNAME>
+```
+aliases: `idcoop user passwd`, `idcoop user chpass`
+
+
+## `idcoop user lock`, `idcoop user unlock` — lock or unlock a user
+
+Locks or unlocks a user. A locked user cannot log in.
+
+```
+idcoop user <lock|unlock> <USERNAME>
+```
+
+- `<USERNAME>`: name of the user to be locked or unlocked
+
+
+## `idcoop user list-all` — list all users
+
+Displays a list of users in tabular form.
+
+```
+idcoop user list-all [--usernames]
+```
+aliases: `idcoop user ls`
+
+- `--usernames`: if specified, only the usernames of users will be shown, one per line.
+
+The output of this command is not considered stable, and should not be used in scripts, unless the `--usernames` option is used.
diff --git a/docs/admin/install.md b/docs/admin/install.md
new file mode 100644
index 0000000..25267fe
--- /dev/null
+++ b/docs/admin/install.md
@@ -0,0 +1 @@
+# Installation
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..5c36747
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,3 @@
+# idCoop: a small identity provider
+
+Welcome to the documentation for idCoop!
diff --git a/flake.nix b/flake.nix
index 40fc947..f0d79fa 100644
--- a/flake.nix
+++ b/flake.nix
@@ -72,6 +72,7 @@
               pkgs.entr
 
               pkgs.mdbook
+              pkgs.mdbook-toc
 
               # Useful for poking at the Postgres database
               pkgs.postgresql