build docs and deploy to github pages

.github/workflows/pages.yml

@@ -0,0 +1,69 @@
+# Inspired from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/.github/workflows/docs.yml
+name: Deploy docs
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+  # TODO: needed ?
+  # schedule:
+  #   - cron: 0 0 * * 1
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Install nix
+        uses: cachix/install-nix-action@v20
+
+      - name: Build docs
+        run: |
+          nix \
+            --print-build-logs \
+            --option keep-going true \
+            --show-trace \
+            build .#manualHtml
+
+          # see https://github.com/actions/deploy-pages/issues/58
+          cp \
+            --recursive \
+            --dereference \
+            --no-preserve=mode,ownership \
+            result/share/doc/selfhostblocks \
+            public
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./public
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/test.yml

@@ -14,4 +14,9 @@ jobs:
       with:
         name: selfhostblocks
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
-    - run: nix flake check -L
+    - run: |
+        nix flake  \
+          --print-build-logs \
+          --option keep-going true \
+          --show-trace \
+          check

docs/man-pages.xml

@@ -0,0 +1,37 @@
+<!-- Copyright (c) 2019-2022, see AUTHORS. Licensed under MIT License, see LICENSE. -->
+<reference xmlns="http://docbook.org/ns/docbook"
+           xmlns:xlink="http://www.w3.org/1999/xlink"
+           xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>Self Host Blocks Reference Pages</title>
+ <info>
+  <author><personname>Self Host Blocks contributors</personname>
+  </author>
+  <copyright><year>2022</year><holder>Self Host Blocks contributors</holder>
+  </copyright>
+ </info>
+ <refentry>
+  <refmeta>
+   <refentrytitle><filename>selfhostblocks-options</filename></refentrytitle>
+   <manvolnum>5</manvolnum>
+   <refmiscinfo class="source">Self Host Blocks</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+   <refname><filename>selfhostblocks-options</filename>
+   </refname><refpurpose>Self Host Blocks configuration specification</refpurpose>
+  </refnamediv>
+  <refsection>
+   <title>Description</title>
+   <para>
+    This contains the module options available for Self Host Blocks.
+   </para>
+  </refsection>
+  <refsection>
+   <title>Options</title>
+   <para>
+    You can use the following options after importing Self Host Blocks as a flake input, then
+    importing the default module for your system.
+   </para>
+   <xi:include href="./nmd-result/selfhostblocks-options.xml" />
+  </refsection>
+ </refentry>
+</reference>

docs/manual.xml

@@ -0,0 +1,71 @@
+<!-- Copyright (c) 2019-2023, see AUTHORS. Licensed under MIT License, see LICENSE. -->
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="book-manual">
+ <info>
+  <title>Self Host Blocks manual</title>
+ </info>
+ <preface>
+  <title>Preface</title>
+  <para>
+   Complete manual for Self Host Blocks, the building blocks for self-hosting with battery included.
+  </para>
+  <para>
+   If you encounter problems or bugs then please report them on the
+   <link xlink:href="https://github.com/ibizaman/selfhostblocks/issues">issue tracker</link>.
+  </para>
+ </preface>
+
+ <appendix xml:id="ch-options">
+  <title>Self Host Blocks configuration options</title>
+  <section xml:id="sec-usage">
+   <title>Usage</title>
+
+   <!--
+   Tags:
+   <title>
+   <section xml:id="sec-NAME">
+   <para>
+   <filename>
+   <replaceable>
+   <varname>
+   <programlisting language="nix">
+   -->
+
+   <para>
+    To use these options, import Self Host Blocks as a flake input, then import the default module for your system.
+<programlisting language="nix">
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    sops-nix.url = "github:Mic92/sops-nix";
+
+    shb.url = "github:ibizaman/selfhostblocks";
+    shb.inputs.nixpkgs.follows = "nixpkgs";
+    shb.inputs.sops-nix.follows = "sops-nix";
+  };
+
+  outputs = { self, nixpkgs, shb }: {
+
+    nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        shb.nixosModules.x86_64-linux.default
+        ./machine.nix
+      ];
+    };
+
+  };
+}
+</programlisting>
+   </para>
+  </section>
+  <section xml:id="sec-options">
+   <title>Options</title>
+
+   <xi:include href="./nmd-result/selfhostblocks-options.xml" />
+  </section>
+ </appendix>
+</book>

flake.lock

@@ -81,11 +81,27 @@
         "type": "github"
       }
     },
+    "nmd": {
+      "locked": {
+        "lastModified": 1672240039,
+        "narHash": "sha256-lmct89fYDOr9YdWVvdJgklv/7WttRSiDAkoi2cvvAW4=",
+        "owner": "gvolpe",
+        "repo": "nmd",
+        "rev": "a59e840c2e8d54415485f349760e1350cb80d911",
+        "type": "github"
+      },
+      "original": {
+        "owner": "gvolpe",
+        "repo": "nmd",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "flake-utils": "flake-utils",
         "nix-flake-tests": "nix-flake-tests",
         "nixpkgs": "nixpkgs",
+        "nmd": "nmd",
         "sops-nix": "sops-nix"
       }
     },

flake.nix

@@ -6,36 +6,72 @@
     sops-nix.url = "github:Mic92/sops-nix";
     nix-flake-tests.url = "github:antifuchs/nix-flake-tests";
     flake-utils.url = "github:numtide/flake-utils";
+    nmd.url = "github:gvolpe/nmd";
   };
 
-  outputs = { nixpkgs, nix-flake-tests, flake-utils, ... }: flake-utils.lib.eachDefaultSystem (system:
+  outputs = { nixpkgs, nix-flake-tests, flake-utils, nmd, ... }: flake-utils.lib.eachDefaultSystem (system:
     let
-      pkgs = nixpkgs.legacyPackages.${system};
+      pkgs = import nixpkgs {
+        inherit system;
+        overlays = [ nmd.overlays.default ];
+      };
+
+      allModules = [
+        modules/blocks/authelia.nix
+        modules/blocks/backup.nix
+        modules/blocks/davfs.nix
+        modules/blocks/ldap.nix
+        modules/blocks/monitoring.nix
+        modules/blocks/nginx.nix
+        modules/blocks/postgresql.nix
+        modules/blocks/ssl.nix
+        modules/blocks/tinyproxy.nix
+        modules/blocks/vpn.nix
+
+        modules/services/arr.nix
+        modules/services/deluge.nix
+        modules/services/hledger.nix
+        modules/services/home-assistant.nix
+        modules/services/jellyfin.nix
+        modules/services/nextcloud-server.nix
+        modules/services/vaultwarden.nix
+      ];
     in
       {
         nixosModules.default = { config, ... }: {
-          imports = [
+          imports = allModules;
-            modules/blocks/authelia.nix
-            modules/blocks/backup.nix
-            modules/blocks/davfs.nix
-            modules/blocks/ldap.nix
-            modules/blocks/monitoring.nix
-            modules/blocks/nginx.nix
-            modules/blocks/postgresql.nix
-            modules/blocks/ssl.nix
-            modules/blocks/tinyproxy.nix
-            modules/blocks/vpn.nix
-
-            modules/services/arr.nix
-            modules/services/deluge.nix
-            modules/services/hledger.nix
-            modules/services/home-assistant.nix
-            modules/services/jellyfin.nix
-            modules/services/nextcloud-server.nix
-            modules/services/vaultwarden.nix
-          ];
         };
 
+        # Inspiration from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/docs/default.nix#L22
+        packages.manualHtml = let
+          setupModule = {
+            _module.args.pkgs = pkgs.lib.mkForce (pkgs.nmd.scrubDerivations "pkgs" pkgs);
+            _module.check = false;
+          };
+
+          modulesDocs = pkgs.nmd.buildModulesDocs {
+            modules = allModules ++ [ setupModule ];
+            moduleRootPaths = [ ../. ];
+            mkModuleUrl = path: "https://myproject.foo/${path}";
+            channelName = "selfhostblocks";
+            docBook = { id = "selfhostblocks-options"; optionIdPrefix = "shb-opt"; };
+          };
+
+          manual = pkgs.nmd.buildDocBookDocs {
+            pathName = "SelfHostBlocks";
+            modulesDocs = [ modulesDocs ];
+            documentsDirectory = ./docs;
+            chunkToc = ''
+              <toc>
+                <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-manual">
+                  <?dbhtml filename="index.html"?>
+                </d:tocentry>
+              </toc>
+            '';
+          };
+        in
+          manual.html;
+
         checks =
           let
             importFiles = files:

modules/blocks/authelia.nix

@@ -14,7 +14,7 @@ in
     subdomain = lib.mkOption {
       type = lib.types.str;
       description = "Subdomain under which Authelia will be served.";
-      example = "ha";
+      example = "auth";
     };
 
     domain = lib.mkOption {
@@ -36,9 +36,17 @@ in
     };
 
     autheliaUser = lib.mkOption {
-      type = lib.types.str;
+      type = lib.types.nullOr lib.types.str;
-      description = "System user for this Authelia instance";
+      description = ''System user for this Authelia instance.
-      default = "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn;
+
+If set to null, defaults to:
+<programlisting language="nix">
+"authelia_" +
+  (builtins.replaceStrings ["-" "."] ["_" "_"]
+    ''${shb.authelia.subdomain}.''${shb.authelia.domain}")
+</programlisting>
+'';
+      default = null;
     };
 
     secrets = lib.mkOption {
@@ -112,7 +120,7 @@ in
 
     services.authelia.instances.${fqdn} = {
       enable = true;
-      user = cfg.autheliaUser;
+      user = cfg.autheliaUser or "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn;
 
       secrets = {
         inherit (cfg.secrets) jwtSecretFile storageEncryptionKeyFile;

modules/blocks/postgresql.nix

@@ -6,7 +6,7 @@ in
   options.shb.postgresql = {
     debug = lib.mkOption {
       type = lib.types.bool;
-      description = lib.mdDocs ''
+      description = lib.mdDoc ''
       Enable debugging options.
 
       Currently enables shared_preload_libraries = "auto_explain, pg_stat_statements"

modules/blocks/vpn.nix

@@ -211,7 +211,7 @@ in
 
           provider = lib.mkOption {
             description = lib.mdDoc "VPN provider, if given uses ready-made configuration.";
-            type = lib.types.nullOf (lib.types.enum [ "nordvpn" ]);
+            type = lib.types.nullOr (lib.types.enum [ "nordvpn" ]);
             default = null;
           };