nix-community · danielfullmer · Apr 16, 2021 · Feb 9, 2021 · Feb 9, 2021 · Feb 9, 2021
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,23 @@
+name: Generate documentation
+
+on:
+  push:
+    branches: [ docs ]
+
+jobs:
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/[email protected]
+      with:
+        fetch-depth: 0
+    - uses: cachix/install-nix-action@v12
+      with:
+        nix_path: nixpkgs=channel:nixos-20.09
+    - run: nix-build ./docs -A manual -o manual
+    - uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./manual/book
+        cname: docs.robotnix.org
diff --git a/NEWS.md b/NEWS.md
@@ -3,6 +3,10 @@ changes occur which require user intervention / configuration changes.  These
 are highlights since the last update, and are not meant to be an exhaustive
 listing of changes. See the git commit log for additional details.
 
+# 2021-XX-XX
+## Backward incompatible changes
+- Renamed `kernel.useCustom` to `kernel.enable`.
+
 # 2021-02-02
 ## Highlights:
 - Updated vanilla flavor to RQ1A.210205.004

diff --git a/default.nix b/default.nix
@@ -11,6 +11,7 @@ let
         options.nixpkgs.overlays = mkOption {
           default = [];
           type = types.listOf types.unspecified;
+          description = "Nixpkgs overlays to override the default packages used while building robotnix.";
         };
 
         config = {

diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,5 @@
+[book]
+language = "en"
+multilingual = false
+src = "src"
+title = "Robotnix"
diff --git a/docs/default.nix b/docs/default.nix
@@ -0,0 +1,57 @@
+{ pkgs ? import ../pkgs { } }:
+
+with pkgs.lib;
+let
+  eval = import ../default.nix { inherit pkgs; configuration = { }; };
+
+  robotnixOptionsDoc = pkgs.nixosOptionsDoc {
+    inherit (eval) options;
+  };
+
+  optionsMd =
+    let
+      options = robotnixOptionsDoc.optionsNix;
+    in
+    concatStrings (map
+      (name:
+        let
+          option = options.${name};
+          body = ''
+            ${option.description}
+
+          '' + optionalString (option ? default) ''
+            Default: `${builtins.toJSON option.default}`
+
+          '' + optionalString (option ? example) ''
+            Example: `${builtins.toJSON option.example}`
+
+          '' + ''
+            Type: ${option.type}
+          '';
+        in
+        ''
+            - `${name}`
+
+          ${concatMapStrings (line: "    ${line}\n") (splitString "\n" body)}
+        ''
+      )
+      (attrNames options));
+in
+{
+  manual = pkgs.stdenv.mkDerivation {
+    name = "manual";
+    phases = [ "unpackPhase" "buildPhase" "installPhase" ];
+    src = ./.;
+    nativeBuildInputs = [ pkgs.mdbook ];
+    buildPhase = ''
+      cp ${builtins.toFile "options.md" optionsMd} src/options.md
+      mdbook build
+    '';
+    installPhase = ''
+      mkdir $out
+      cp -R book $out/book
+      cp -R src $out/src
+      cp book.toml $out/book.toml
+    '';
+  };
+}
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,10 @@
+# Summary
+
+- [Welcome to Robotnix](welcome.md)
+- [Tutorials]()
+  - [Installation](installation.md)
+  - [OTA updates](ota.md)
+  - [F-Droid repositories](f-droid.md)
+  - [Remote attestation](attestation.md)
+- [Reference]()
+  - [Options](options.md)
diff --git a/docs/attestation.md → docs/src/attestation.md b/docs/attestation.md → docs/src/attestation.md
diff --git a/docs/f-droid.md → docs/src/f-droid.md b/docs/f-droid.md → docs/src/f-droid.md
@@ -10,14 +10,11 @@ the public key.
 
 We'll take the microG repository as an example.  The repository is located at
 https://microg.org/fdroid/repo.  To obtain the repository index download the
-`index.jar` file from the repository root:
+`index.xml` file from the repository root:
 ```console
-$ curl -LO https://microg.org/fdroid/repo/index.jar
+$ curl -LO https://microg.org/fdroid/repo/index.xml
 ```
-Java Archives are simply ZIP files with a certain structure, so to get the
-repository index out of this file, we unzip the contained `index.xml`:
-```console
-$ unzip index.jar index.xml
+
 ```
 The content of this XML file contains metadata about the repository, including
 the public key:

diff --git a/docs/installation.md → docs/src/installation.md b/docs/installation.md → docs/src/installation.md
diff --git a/docs/src/options.md b/docs/src/options.md
diff --git a/docs/ota.md → docs/src/ota.md b/docs/ota.md → docs/src/ota.md
diff --git a/docs/src/welcome.md b/docs/src/welcome.md
@@ -0,0 +1,6 @@
+# robotnix - Build Android (AOSP) using Nix
+
+Robotnix is a build system for Android (AOSP) images on top of the Nix package
+manager.  Instead of having to follow complicated instructions to install
+several build tools and fetch source code from multiple sources, robotnix
+encapsulates all this complexity in a simple Nix expression.
diff --git a/flavors/grapheneos/default.nix b/flavors/grapheneos/default.nix
@@ -68,7 +68,7 @@ in mkIf (config.flavor == "grapheneos") (mkMerge [
   # audit devices using the official upstream build
 }
 (mkIf (elem config.deviceFamily phoneDeviceFamilies) {
-  kernel.useCustom = mkDefault true;
+  kernel.enable = mkDefault true;
   kernel.src = mkDefault config.source.dirs."kernel/google/${config.kernel.name}".src;
   kernel.configName = config.device;
   kernel.relpath = "device/google/${config.device}-kernel";

diff --git a/flavors/vanilla/default.nix b/flavors/vanilla/default.nix
@@ -118,7 +118,7 @@ in mkIf (config.flavor == "vanilla") (mkMerge [
 
   # TODO: Currently, only build kernel for marlin since it needs verity key in build.
   # Could also build for other devices, like is done for Android 11
-  kernel.useCustom = mkDefault config.signing.enable;
+  kernel.enable = mkDefault config.signing.enable;
 })
 
 ]))
@@ -162,7 +162,7 @@ in mkIf (config.flavor == "vanilla") (mkMerge [
   kernelMetadata = (lib.importJSON ./kernel-metadata.json).${kernelTag};
   kernelHashes = (lib.importJSON ./kernel-hashes.json).${kernelTag};
 in {
-  kernel.useCustom = mkDefault true;
+  kernel.enable = mkDefault true;
   kernel.configName = mkMerge [
     (mkIf (elem config.deviceFamily [ "taimen" "muskie" ]) "wahoo")
     (mkIf (config.deviceFamily == "crosshatch") "b1c1")

diff --git a/modules/apps/auditor.nix b/modules/apps/auditor.nix
@@ -12,16 +12,16 @@ in
 
       domain = mkOption {
         type = types.str;
-        default = "attestation.app";
-        description = "Domain running the AttestationServer (over https) for remote verification";
+        description = "Domain running the AttestationServer (over HTTPS) for remote verification";
+        example = "attestation.example.com";
       };
     };
   };
 
   config = mkIf cfg.enable {
     assertions = [ {
       assertion = builtins.elem config.device supportedDevices;
-      message = "Device ${config.device} is currently unsupported for use with auditor app.";
+      message = "Device ${config.device} is currently unsupported for use with Auditor app.";
     } ];
 
     apps.prebuilt.Auditor = {

diff --git a/modules/apps/fdroid.nix b/modules/apps/fdroid.nix
@@ -14,41 +14,55 @@ in
   options.apps.fdroid = {
     enable = mkEnableOption "F-Droid";
 
-    # See apps/src/main/java/org/fdroid/fdroid/data/DBHelper.java in fdroid source
-    # Note that changes to this setting will only take effect on a freshly
-    # installed device--or if the FDroid storage is cleared
+    # See also `apps/src/main/java/org/fdroid/fdroid/data/DBHelper.java` in F-Droid source
     additionalRepos = mkOption {
       default = {};
+      description = ''
+        Additional F-Droid repositories to include in the default build.
+        Note that changes to this setting will only take effect on a freshly
+        installed device--or if the F-Droid storage is cleared.
+      '';
       type = types.attrsOf (types.submodule ({ name, ... }: {
         options = {
-          enable = mkEnableOption name;
+          enable = mkOption {
+            default = false;
+            type = types.bool;
+            description = "Whether to enable this repository by default in F-Droid.";
+          };
 
           name = mkOption {
             default = name;
             type = types.str;
+            description = "Display name to use for this repository";
           };
 
           url = mkOption {
             type = types.str;
+            description = "URL for F-Droid repository";
           };
 
           description = mkOption {
-            default = "Empty description"; # fdroid parsing of additional_repos.xml requires all items to have text
             type = types.str;
+            default = "Empty description"; # fdroid parsing of additional_repos.xml requires all items to have text
+            description = "Longer textual description of this repository";
           };
 
-          version = mkOption { # Not sure what this one is for exactly
-            default = 1;
+          version = mkOption {
             type = types.int;
+            default = 0;
+            description = "Which version of fdroidserver built this repo";
+            internal = true;
           };
 
-          pushRequests = mkOption { # Repo metadata can specify apps to be installed/removed
+          pushRequests = mkOption {
             type = types.strMatching "(ignore|prompt|always)";
+            description = "Allow this repository to specify apps which should be automatically installed/uninstalled";
             default = "ignore";
           };
 
           pubkey = mkOption { # Wew these are long AF. TODO: Some way to generate these?
             type = types.str;
+            description = "Public key associated with this repository. Can be found in `/index.xml` under the repo URL.";
           };
         };
       }));

diff --git a/modules/apps/prebuilt.nix b/modules/apps/prebuilt.nix
@@ -36,22 +36,27 @@ in
   options = {
     apps.prebuilt = mkOption {
       default = {};
+      description = "Prebuilt APKs to include in the robotnix build";
+
       type = let
         _config = config;
       in types.attrsOf (types.submodule ({ name, config, ... }: {
         options = {
           name = mkOption {
             default = name;
-            type = types.str; # No spaces (use strMatching?)
+            description = "Name of application. (No spaces)";
+            type = types.str; # TODO: Use strMatching to enforce no spaces?
           };
 
           apk = mkOption {
             type = types.path;
+            description = "APK file to include in build";
           };
 
           signedApk = mkOption {
             type = types.path;
             internal = true;
+            description = "Robotnix-signed version of APK file";
           };
 
           fingerprint = mkOption {
@@ -62,18 +67,19 @@ in
           };
 
           packageName = mkOption { # Only used with privapp permissions
-            type = types.str;
-            description = "example: com.android.test";
+            description = "APK's Java-style package name (applicationId). This setting only necessary to be set if also using `privappPermissions`.";
+            type = types.strMatching "[a-zA-Z0-9_.]*";
+            example = "com.android.test";
           };
 
           certificate = mkOption {
             default = toLower name;
             type = types.str;
             description = ''
-              Certificate name to sign apk with.  Defaults to the name of the prebuilt app.
-              If it is a device-specific certificate, the cert/key will be ''${keyStorePath}/''${device}/''${certificate}.{x509.pem,pk8}
-              Otherwise, it will be ''${keyStorePath}/''${certificate}.{x509.pem,pk8}
-              Finally, the special string "PRESIGNED" will just use the apk as-is.
+              Name of certificate to sign APK with.  Defaults to the name of the prebuilt app.
+              If it is a device-specific certificate, the cert/key should be under `''${keyStorePath}/''${device}/''${certificate}.{x509.pem,pk8}`.
+              Otherwise, it should be `''${keyStorePath}/''${certificate}.{x509.pem,pk8}`.
+              Finally, the special string "PRESIGNED" will just use the APK as-is.
             '';
           };
 
@@ -85,12 +91,14 @@ in
           privileged = mkOption {
             default = false;
             type = types.bool;
+            description = "Whether this APK should be included as a privileged application.";
           };
 
           privappPermissions = mkOption {
             default = [];
             type = types.listOf types.str;
             description = ''
+              Privileged permissions to apply to this application.
               See https://developer.android.com/reference/android/Manifest.permission and note permissions which say
               "not for use by third-party applications".
             '';
@@ -100,24 +108,28 @@ in
           defaultPermissions = mkOption {
             default = [];
             type = types.listOf types.str;
-            description = ''
-              Permissions which are to be enabled by default without user prompting
-            '';
+            description = "Permissions to be enabled by default without user prompting.";
             example = ''[ "INSTALL_PACKAGES" ]'';
           };
 
           partition = mkOption {
+            description = "Partition on which to place this app";
             type = types.strMatching "(vendor|system|product)";
           };
 
           allowInPowerSave = mkOption {
             default = false;
             type = types.bool;
+            description = ''
+              Whether to allow this application to operate in \"power save\" mode.
+              Disables battery optimization for this app.
+            '';
           };
 
           extraConfig = mkOption {
             default = "";
             type = types.lines;
+            internal = true;
           };
         };
 

diff --git a/modules/apps/updater.nix b/modules/apps/updater.nix
@@ -14,7 +14,7 @@ in
 {
   options = {
     apps.updater = {
-      enable = mkEnableOption "updater";
+      enable = mkEnableOption "OTA Updater";
 
       url = mkOption {
         type = types.str;