Editing pass to make option docs consistent

shared/backups/options.nix

@@ -62,16 +62,23 @@ with lib;
     environmentFile = mkOption {
       type = types.str;
       description = mdDoc ''
-        Environment file to be passed to the systemd services.  This needs to contain:
+        Environment file to pass secrets into the service.  This is of the form:
 
-        - `PASSPHRASE` - the password duplicity uses to encrypt the files
-        - `AWS_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION` -
-          the AWS credentials used to upload the backup to s3 and publish to the
-          SNS topic
-        - `TOPIC_ARN` - the SNS topic to publish to if an error occurs
+        ```text
+        # Duplicity encryption password
+        PASSPHRASE="..."
+
+        # AWS S3 & SNS credentials
+        AWS_ACCESS_KEY="..."
+        AWS_SECRET_ACCESS_KEY="..."
+        AWS_DEFAULT_REGION="..."
+
+        # SNS topic to send alerts to
+        TOPIC_ARN="..."
+        ```
 
         If any of the `scripts` or `pythonScripts` need secrets, those should be
-        specified here.
+        specified in this file as well.
       '';
     };
 

shared/bookdb/options.nix

@@ -8,15 +8,15 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the bookdb service.
+        Enable the [bookdb](https://github.com/barrucadu/bookdb) service.
       '';
     };
 
     port = mkOption {
       type = types.int;
       default = 46667;
       description = mdDoc ''
-        Port (on 127.0.0.1) to expose the bookdb service on.
+        Port (on 127.0.0.1) to expose bookdb on.
       '';
     };
 
@@ -48,8 +48,8 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Whether to launch the service in "read-only" mode.  Enable this if
-        exposing it to a public network.
+        Launch the service in "read-only" mode.  Enable this if exposing it to a
+        public network.
       '';
     };
 

shared/bookmarks/options.nix

@@ -8,15 +8,15 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the bookmarks service.
+        Enable the [bookmarks](https://github.com/barrucadu/bookmarks) service.
       '';
     };
 
     port = mkOption {
       type = types.int;
       default = 48372;
       description = mdDoc ''
-        Port (on 127.0.0.1) to expose the bookmarks service on.
+        Port (on 127.0.0.1) to expose bookmarks on.
       '';
     };
 
@@ -48,17 +48,22 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Whether to launch the service in "read-only" mode.  Enable this if
-        exposing it to a public network.
+        Launch the service in "read-only" mode.  Enable this if exposing it to a
+        public network.
       '';
     };
 
     environmentFile = mkOption {
       type = types.nullOr types.str;
       default = null;
       description = mdDoc ''
-        Environment file to be passed to the systemd services.  This needs to
-        contain a `YOUTUBE_API_KEY` if not running in read-only mode.
+        Environment file to pass secrets into the service.  This is of the form:
+
+        ```text
+        YOUTUBE_API_KEY="..."
+        ```
+
+        This is only required if not running in read-only mode.
       '';
     };
   };

shared/concourse/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the Concourse CI service.
+        Enable the [Concourse CI](https://concourse-ci.org/) service.
       '';
     };
 
@@ -32,15 +32,15 @@ with lib;
       type = types.int;
       default = 46498;
       description = mdDoc ''
-        Port (on 127.0.0.1) to expose the Concourse CI web UI on.
+        Port (on 127.0.0.1) to expose Concourse CI on.
       '';
     };
 
     metricsPort = mkOption {
       type = types.int;
       default = 45811;
       description = mdDoc ''
-        Port (on 127.0.0.1) to expose the Concourse CI Prometheus metrics on.
+        Port (on 127.0.0.1) to expose the Prometheus metrics on.
       '';
     };
 
@@ -65,13 +65,18 @@ with lib;
     environmentFile = mkOption {
       type = types.str;
       description = mdDoc ''
-        Environment file to be passed into the containers.  This needs to contain:
+        Environment file to pass secrets into the service.  This is of the form:
 
-        - `CONCOURSE_GITHUB_CLIENT_ID` / `CONCOURSE_GITHUB_CLIENT_SECRET` - the
-          GitHub OAuth credentials used for user authentication
-        - `CONCOURSE_AWS_SSM_REGION` / `CONCOURSE_AWS_SSM_ACCESS_KEY` /
-          `CONCOURSE_AWS_SSM_SECRET_KEY` - the AWS credentials used to fetch
-          secrets from SSM
+        ```text
+        # GitHub OAuth credentials
+        CONCOURSE_GITHUB_CLIENT_ID="..."
+        CONCOURSE_GITHUB_CLIENT_SECRET="..."
+
+        # AWS SSM credentials
+        CONCOURSE_AWS_SSM_REGION="..."
+        CONCOURSE_AWS_SSM_ACCESS_KEY="..."
+        CONCOURSE_AWS_SSM_SECRET_KEY="..."
+        ```
       '';
     };
   };

shared/erase-your-darlings/options.nix

@@ -16,8 +16,7 @@ with lib;
     barrucaduPasswordFile = mkOption {
       type = types.str;
       description = mdDoc ''
-        Path to a file containing the hashed password for `barrucadu`.  This
-        file must be available in early boot.
+        File containing the hashed password for `barrucadu`.
 
         If using [sops-nix](https://github.com/Mic92/sops-nix) set the
         `neededForUsers` option on the secret.

shared/finder/options.nix

@@ -15,15 +15,15 @@ with lib;
     image = mkOption {
       type = types.str;
       description = mdDoc ''
-        Container image to use.
+        Container image to run.
       '';
     };
 
     port = mkOption {
       type = types.int;
       default = 44986;
       description = mdDoc ''
-        Port (on 127.0.0.1) to expose the finder service on.
+        Port (on 127.0.0.1) to expose finder on.
       '';
     };
 

shared/foundryvtt/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the FoundryVTT service.
+        Enable the [FoundryVTT](https://foundryvtt.com/) service.
       '';
     };
 

shared/minecraft/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the Minecraft service.
+        Enable the [Minecraft](https://www.minecraft.net/en-us) service.
       '';
     };
 
@@ -31,7 +31,7 @@ with lib;
               type = types.bool;
               default = true;
               description = mdDoc ''
-                Start this server on boot.
+                Start the server automatically on boot.
               '';
             };
 

shared/oci-containers/options.nix

@@ -6,14 +6,14 @@ let
     host = mkOption {
       type = types.int;
       description = mdDoc ''
-        Host port (on 127.0.0.1) to expose the inner port on.
+        Host port (on 127.0.0.1) to expose the container port on.
       '';
     };
 
     inner = mkOption {
       type = types.int;
       description = mdDoc ''
-        Container port.
+        The container port to expose to the hosti.
       '';
     };
   };
@@ -23,10 +23,13 @@ let
       type = types.nullOr types.str;
       default = null;
       description = mdDoc ''
-        Name of the volume.  This creates a bind-mount to
-        `''${volumeBaseDir}/''${volumeSubDir}/''${name}`.
+        Name of the volume.  This is equivalent to:
 
-        Exactly one of this or `''${host}` must be specified.
+        ```nix
+        host = "''${volumeBaseDir}/''${volumeSubDir}/''${name}";
+        ```
+
+        This option c.logonflicts with `''${host}`.
       '';
     };
 
@@ -36,7 +39,7 @@ let
       description = mdDoc ''
         Directory on the host to bind-mount into the container.
 
-        Exactly one of this or `''${name}` must be specified.
+        This option conflicts with `''${name}`.
       '';
     };
 
@@ -54,7 +57,7 @@ let
       type = types.bool;
       default = true;
       description = mdDoc ''
-        Whether to start the container automatically on boot.
+        Start the container automatically on boot.
       '';
     };
 
@@ -69,8 +72,10 @@ let
     dependsOn = mkOption {
       type = types.listOf types.str;
       default = [ ];
+      example = [ "concourse-db" ];
       description = mdDoc ''
-        Other containers that this one depends on.
+        Other containers that this one depends on, in `''${pod}-''${name}`
+        format.
       '';
     };
 
@@ -151,8 +156,7 @@ let
       type = types.bool;
       default = true;
       description = mdDoc ''
-        Whether to pull the container image when starting (useful for `:latest`
-        images).
+        Pull the container image when starting (useful for `:latest` images).
       '';
     };
   };

shared/options.nix

@@ -8,7 +8,13 @@ with lib;
       type = types.nullOr types.str;
       default = null;
       description = mdDoc ''
-        File containing IPs to block.
+        File containing IPs to block.  This is of the form:
+
+        ```text
+        ip-address # comment
+        ip-address # comment
+        ...
+        ```
       '';
     };
   };

shared/pleroma/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the Pleroma service.
+        Enable the [Pleroma](https://pleroma.social/) service.
       '';
     };
 
@@ -40,7 +40,7 @@ with lib;
       type = types.nullOr types.path;
       default = null;
       description = mdDoc ''
-        Path to the favicon file.
+        File to use for the favicon.
       '';
     };
 
@@ -73,14 +73,14 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Whether to allow new users to sign up.
+        Allow new users to sign up.
       '';
     };
 
     secretsFile = mkOption {
       type = types.str;
       description = mdDoc ''
-        Path to the secret configuration file.
+        File containing secret configuration.
 
         See the Pleroma documentation for what this needs to contain.
       '';

shared/resolved/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the resolved service.
+        Enable the [resolved](https://github.com/barrucadu/resolved) service.
       '';
     };
 

shared/rtorrent/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the rTorrent service.
+        Enable the [rTorrent](https://github.com/rakshasa/rtorrent) service.
       '';
     };
 
@@ -74,14 +74,14 @@ with lib;
         type = types.bool;
         default = true;
         description = mdDoc ''
-          Enable the [flood](https://flood.js.org/) web UI.
+          Enable the [Flood](https://flood.js.org/) web UI.
         '';
       };
       port = mkOption {
         type = types.int;
         default = 45904;
         description = mdDoc ''
-          Port (on 127.0.0.1) to expose the flood service on.
+          Port (on 127.0.0.1) to expose Flood on.
         '';
       };
     };

shared/umami/options.nix

@@ -8,7 +8,7 @@ with lib;
       type = types.bool;
       default = false;
       description = mdDoc ''
-        Enable the umami service.
+        Enable the [umami](https://umami.is/) service.
       '';
     };
 
@@ -39,8 +39,11 @@ with lib;
     environmentFile = mkOption {
       type = types.str;
       description = mdDoc ''
-        Environment file to be pased to the container.  This needs to contain a
-        `HASH_SALT`.
+        Environment file to pass secrets into the service.  This is of the form:
+
+        ```text
+        HASH_SALT="..."
+        ```
       '';
     };
   };