feat(docs): add website with mdBook and automated deployment

- Add GitHub Actions workflow for building and deploying docs
- Set up mdBook documentation structure with getting started guides
- Add comprehensive API documentation and type descriptions
- Update flake.nix to support website generation
- Fix type name from "optional" to "option" in RON generator

.github/workflows/website.yml

@@ -0,0 +1,53 @@
+name: Build & deploy website
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - '**.nix'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '**.nix'
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Nix
+        uses: cachix/install-nix-action@v30
+      - name: Run build
+        run: |
+          nix build \
+            --print-build-logs \
+            --show-trace \
+            '.#site'
+      - name: Get artifact directory
+        id: find-path
+        run: |
+          # exit if no `result` from `nix build`
+          [ ! -L result ] && exit 1
+          echo "path=$(readlink -f result)" >> "$GITHUB_OUTPUT"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ steps.find-path.outputs.path }}
+  deploy:
+    name: Deploy site
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    permissions:
+      id-token: write
+      pages: write
+    steps:
+      - name: Deploy to GitHub pages
+        id: deploy
+        uses: actions/deploy-pages@v4

docs/book.toml

@@ -0,0 +1,12 @@
+[book]
+title = "cosmic-manager"
+authors = ["HeitorAugustoLN"]
+description = "Manage COSMIC desktop declaratively using home-manager"
+language = "en"
+multilingual = false
+src = "src"
+
+[output.html]
+no-section-label = true
+git-repository-url = "https://github.com/HeitorAugustoLN/cosmic-manager"
+git-repository-icon = "fa-github"

docs/generate-website.nix

@@ -0,0 +1,47 @@
+{
+  stdenvNoCC,
+  writeShellApplication,
+  mdbook,
+  python3,
+}:
+{ options, ... }@args:
+stdenvNoCC.mkDerivation (
+  finalAttrs:
+  args
+  // {
+    nativeBuildInputs = [ mdbook ];
+
+    dontPatch = true;
+    dontConfigure = true;
+    doCheck = false;
+
+    buildPhase = ''
+      runHook preBuild
+
+      ln -s ${options} src/options/README.md
+      mdbook build
+
+      runHook postBuild
+    '';
+
+    installPhase = ''
+      runHook preInstall
+
+      mv book $out
+
+      runHook postInstall
+    '';
+
+    passthru = {
+      serve = writeShellApplication {
+        name = "serve";
+
+        runtimeInputs = [ python3 ];
+
+        text = ''
+          python -m http.server --bind 127.0.0.1 --directory ${finalAttrs.finalPackage}
+        '';
+      };
+    };
+  }
+)

docs/options.nix

@@ -0,0 +1,58 @@
+{ lib, nixosOptionsDoc }:
+{
+  version,
+  modules ? [ moduleRoot ],
+  moduleRoot,
+}:
+let
+  baseDeclarationUrl = "https://github.com/HeitorAugustoLN/cosmic-manager/blob/main";
+  declarationIsOurs = declaration: lib.hasPrefix (toString moduleRoot) (toString declaration);
+  declarationSubpath = declaration: lib.removePrefix (toString ../. + "/") (toString declaration);
+
+  toGithubDeclaration =
+    declaration:
+    let
+      subpath = declarationSubpath declaration;
+    in
+    {
+      url = "${baseDeclarationUrl}/${subpath}";
+      name = "<cosmic-manager/${subpath}>";
+    };
+
+  evaluatedModules = lib.evalModules {
+    modules = modules ++ [
+      {
+        options.system.nixos.release = lib.mkOption {
+          type = lib.types.str;
+          default = lib.trivial.release;
+          readOnly = true;
+        };
+
+        config = {
+          _module.check = false;
+        };
+      }
+    ];
+  };
+
+  optionsDoc = nixosOptionsDoc {
+    options = builtins.removeAttrs evaluatedModules.options [
+      "_module"
+      "system"
+    ];
+
+    transformOptions =
+      option:
+      option
+      // {
+        declarations = map (
+          declaration: if declarationIsOurs declaration then toGithubDeclaration declaration else declaration
+        ) option.declarations;
+      };
+
+    documentType = "none";
+    revision = version;
+    warningsAreErrors = false;
+  };
+in
+optionsDoc.optionsCommonMark

docs/src/README.md

@@ -0,0 +1,18 @@
+# cosmic-manager
+
+Manage COSMIC desktop declaratively using `home-manager`.
+
+## What is cosmic-manager?
+
+`cosmic-manager` is a declarative way to manage your COSMIC desktop using `home-manager`.
+It provides a set of modules that can be used to configure your favorite desktop environment.
+This means your settings are easy to backup, share, replicate and restore.
+
+## Getting started
+
+Ready to give it a try? Check out the [Getting started](getting-started/index.md) guide.
+Once you're done, you can take a look at all of our available options in the [Options](options/index.md) section.
+
+## Found a bug?
+
+Please report it [here](https://github.com/HeitorAugustoLN/cosmic-manager/issues/new).

docs/src/SUMMARY.md

@@ -0,0 +1,9 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Getting started](getting-started/README.md)
+  - [Stable Nix](getting-started/stable-nix.md)
+  - [Flakes](getting-started/flakes.md)
+
+- [Options](options/README.md)

docs/src/getting-started/README.md

@@ -0,0 +1,8 @@
+# Getting started
+
+`cosmic-manager` supports both stable Nix and [Flakes](https://wiki.nixos.org/wiki/Flakes). So you
+can choose the one that best fits your needs. Follow the steps below to get started with managing
+your COSMIC desktop declaratively using `cosmic-manager`.
+
+- [Stable Nix](stable-nix.md)
+- [Flakes](flakes.md)

docs/src/getting-started/flakes.md

@@ -0,0 +1,77 @@
+# Flakes
+
+Flakes are the preferred way to use `cosmic-manager`, offering a modern and reproducible way to manage your COSMIC desktop.
+
+If you have Flakes enabled, this will be the easiest and most flexible method to get started.
+
+## Adding `cosmic-manager` as an Input
+
+First, add `cosmic-manager` to the inputs in your `flake.nix` file. Here’s an example:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "nixpkgs/nixos-unstable";
+    cosmic-manager = {
+      url = "github:HeitorAugustoLN/cosmic-manager";
+      inputs = {
+        nixpkgs.follows = "nixpkgs";
+        home-manager.follows = "home-manager";
+      };
+    };
+    home-manager = {
+      url = "github:nix-community/home-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
+    # Outputs will depend on your setup (home-manager as NixOS module or standalone home-manager).
+  };
+}
+```
+
+## Using `cosmic-manager` with a `home-manager` as NixOS module installation
+
+If you’re using `home-manager` as a NixOS module, your `flake.nix` file might look like this:
+
+```nix
+{
+  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
+    nixosConfigurations.my-computer = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        home-manager.nixosModules.home-manager
+        {
+          home-manager.users.cosmic-user = {
+            imports = [
+              ./home.nix
+              cosmic-manager.homeManagerModules.cosmic-manager
+            ];
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+## Using `cosmic-manager` with a standalone `home-manager` installation
+
+If you’re using `home-manager` as a standalone tool, your `flake.nix` file might look like this:
+
+```nix
+{
+  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
+    homeConfigurations."cosmic-user@my-computer" = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      modules = [
+        ./home.nix
+        cosmic-manager.homeManagerModules.cosmic-manager
+      ];
+    };
+  };
+}
+```
+
+Follow this guide, and you’ll have `cosmic-manager` up and running with Flakes in no time!

docs/src/getting-started/stable-nix.md

@@ -0,0 +1,104 @@
+# Stable Nix
+
+When using stable Nix, you have several options to install `cosmic-manager` based on your preferences and setup. Choose one of the methods below to get started.
+
+## Option 1: Using `npins`
+
+[`npins`](https://github.com/andir/npins) simplifies the process of ["pinning"](https://nix.dev/tutorials/first-steps/towards-reproducibility-pinning-nixpkgs) external dependencies for your configuration.
+
+### Steps:
+
+1. Ensure you have followed [the `npins` getting started guide](https://github.com/andir/npins#getting-started).
+2. Add `cosmic-manager` to your configuration:
+
+```sh
+npins add --name cosmic-manager github HeitorAugustoLN cosmic-manager
+```
+
+3. Update your Nix configuration:
+
+**With `home-manager` integrated into NixOS:**
+
+```nix
+let
+  sources = import ./npins;
+in
+{
+  home-manager.users.cosmic-user = {
+    imports = [
+      (sources.cosmic-manager + "/modules")
+    ];
+
+    wayland.desktopManager.cosmic.enable = true;
+  };
+}
+```
+
+**With standalone `home-manager`:**
+
+```nix
+let
+  sources = import ./npins.nix;
+in
+{
+  imports = [
+    (sources.cosmic-manager + "/modules")
+  ];
+
+  home.username = "cosmic-user";
+  programs.home-manager.enable = true;
+
+  wayland.desktopManager.cosmic.enable = true;
+}
+```
+
+## Option 2: Using Channels
+
+[Nix channels](https://nixos.org/manual/nix/stable/command-ref/nix-channel.html) offer a simple way to download, update, and use `cosmic-manager` modules. However, this approach sacrifices reproducibility across different machines.
+
+### Steps:
+
+1. Add the `cosmic-manager` channel:
+
+```sh
+sudo nix-channel --add https://github.com/HeitorAugustoLN/cosmic-manager/archive/main.tar.gz cosmic-manager
+sudo nix-channel --update
+```
+
+2. Update your Nix configuration:
+
+**With `home-manager` integrated into NixOS:**
+
+```nix
+{
+  home-manager.users.cosmic-user = {
+    imports = [
+      <cosmic-manager/modules>
+    ];
+
+    wayland.desktopManager.cosmic.enable = true;
+  };
+}
+```
+
+**With standalone `home-manager`:**
+
+```nix
+{
+  imports = [
+    <cosmic-manager/modules>
+  ];
+
+  home.username = "cosmic-user";
+  programs.home-manager.enable = true;
+
+  wayland.desktopManager.cosmic.enable = true;
+}
+```
+
+## Which Option Should I Choose?
+
+- **Use `npins`**: If you want better reproducibility and a cleaner way to manage external dependencies.
+- **Use Channels**: If you prefer a simpler setup and are okay with sacrificing strict reproducibility.
+
+With either method, you’re set to manage your COSMIC desktop declaratively!