Merge pull request #201 from hercules-ci/links

Fix doc links

src/nix/lib.nix

@@ -3,13 +3,17 @@ let
 
   link = url: text: ''[${text}](${url})'';
 
-  dockerComposeRef = fragment:
-    ''See ${link "https://docs.docker.com/compose/compose-file/#${fragment}" "Docker Compose#${fragment}"}'';
+  serviceRef = fragment:
+    ''See ${link "https://docs.docker.com/compose/compose-file/05-services/#${fragment}" "Docker Compose Services #${fragment}"}'';
+
+  networkRef = fragment:
+    ''See ${link "https://docs.docker.com/compose/compose-file/06-networks/#${fragment}" "Docker Compose Network #${fragment}"}'';
 
 in
 {
   inherit
-    dockerComposeRef
     link
+    networkRef
+    serviceRef
     ;
 }

src/nix/modules/composition/networks.nix

@@ -7,7 +7,7 @@ let
     types
     ;
   inherit (import ../../lib.nix { inherit lib; })
-    dockerComposeRef
+    link
     ;
 in
 {
@@ -19,7 +19,7 @@ in
         ];
       });
       description = ''
-        ${dockerComposeRef "networks-top-level-element"}
+        See ${link "https://docs.docker.com/compose/compose-file/06-networks/" "Docker Compose Networks"}
       '';
     };
     enableDefaultNetwork = mkOption {

src/nix/modules/networks/network.nix

@@ -7,7 +7,7 @@ let
     types
     ;
   inherit (import ../../lib.nix { inherit lib; })
-    dockerComposeRef
+    networkRef
     ;
 in
 {
@@ -15,21 +15,21 @@ in
     driver = mkOption {
       description = ''
         `"none"`, `"host"`, or a platform-specific value.
-        ${dockerComposeRef "driver"}
+        ${networkRef "driver"}
       '';
       type = types.str;
     };
 
     driver_opts = mkOption {
       description = ''
-        ${dockerComposeRef "driver_opts"}
+        ${networkRef "driver_opts"}
       '';
       type = types.lazyAttrsOf types.raw or types.unspecified;
     };
 
     attachable = mkOption {
       description = ''
-        ${dockerComposeRef "attachable"}
+        ${networkRef "attachable"}
       '';
       type = types.bool;
       example = true;
@@ -39,7 +39,7 @@ in
       description = ''
         Whether we've entered the 21st century yet.
         
-        ${dockerComposeRef "enable_ipv6"}
+        ${networkRef "enable_ipv6"}
       '';
       type = types.bool;
     };
@@ -49,7 +49,7 @@ in
       description = ''
         Manage IP addresses.
 
-        ${dockerComposeRef "ipam"}
+        ${networkRef "ipam"}
       '';
       type = types.raw or types.unspecified;
     };
@@ -58,7 +58,7 @@ in
       description = ''
         Achieves "external isolation".
 
-        ${dockerComposeRef "internal"}
+        ${networkRef "internal"}
       '';
       defaultText = false;
       type = types.bool;
@@ -68,7 +68,7 @@ in
       description = ''
         Metadata.
 
-        ${dockerComposeRef "labels"}
+        ${networkRef "labels"}
       '';
       # no list support, because less expressive wrt overriding
       type = types.attrsOf types.str;
@@ -79,7 +79,7 @@ in
         When `true`, don't create or destroy the network, but assume that it
         exists.
 
-        ${dockerComposeRef "external"}
+        ${networkRef "external"}
       '';
       type = types.bool;
     };
@@ -92,7 +92,7 @@ in
 
         Note the `default` network's default `name` is set to `project.name` by Arion.
 
-        ${dockerComposeRef "name"}
+        ${networkRef "name"}
       '';
       type = types.str;
     };

src/nix/modules/service/docker-compose-service.nix

@@ -12,15 +12,9 @@ let
 
   inherit (import ../../lib.nix { inherit lib; })
     link
-    dockerComposeRef
+    serviceRef
     ;
 
-  dockerComposeKitchenSink = ''
-    Analogous to the `docker run` counterpart.
-
-    ${dockerComposeRef "domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir"}
-  '';
-
   cap_add = lib.attrNames (lib.filterAttrs (name: value: value == true) config.service.capabilities);
   cap_drop = lib.attrNames (lib.filterAttrs (name: value: value == false) config.service.capabilities);
 
@@ -56,12 +50,12 @@ in
     service.volumes = mkOption {
       type = listOf types.unspecified;
       default = [];
-      description = dockerComposeRef "volumes";
+      description = serviceRef "volumes";
     };
     service.tmpfs = mkOption {
       type = listOf types.str;
       default = [];
-      description = dockerComposeRef "tmpfs";
+      description = serviceRef "tmpfs";
     };
     service.build.context = mkOption {
       type = nullOr str;
@@ -69,44 +63,48 @@ in
       description = ''
         Locates a Dockerfile to use for creating an image to use in this service.
 
-        ${dockerComposeRef "context"}
+        https://docs.docker.com/compose/compose-file/build/#context
       '';
     };
     service.hostname = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeKitchenSink;
+      description = ''
+        ${serviceRef "hostname"}
+      '';
     };
     service.tty = mkOption {
       type = nullOr bool;
       default = null;
-      description = dockerComposeKitchenSink;
+      description = ''
+        ${serviceRef "tty"}
+      '';
     };
     service.environment = mkOption {
       type = attrsOf (either str int);
       default = {};
-      description = dockerComposeRef "environment";
+      description = serviceRef "environment";
     };
     service.image = mkOption {
       type = str;
-      description = dockerComposeRef "image";
+      description = serviceRef "image";
     };
     service.command = mkOption {
       type = nullOr types.unspecified;
       default = null;
-      description = dockerComposeRef "command";
+      description = serviceRef "command";
     };
     service.container_name = mkOption {
       type = nullOr types.str;
       default = null;
-      description = dockerComposeRef "container_name";
+      description = serviceRef "container_name";
     };
     service.depends_on =
       let conditionsModule = {
             options = {
               condition = mkOption {
                 type = enum ["service_started" "service_healthy" "service_completed_successfully"];
-                description = dockerComposeRef "depends_on";
+                description = serviceRef "depends_on";
                 default = "service_started";
               };
             };
@@ -114,10 +112,10 @@ in
        in mkOption {
          type = either (listOf str) (attrsOf (submodule conditionsModule));
          default = [];
-         description = dockerComposeRef "depends_on";
+         description = serviceRef "depends_on";
        };
     service.healthcheck = mkOption {
-      description = dockerComposeRef "healthcheck";
+      description = serviceRef "healthcheck";
       type = submodule ({ config, options, ...}: {
         options = {
           _out = mkOption {
@@ -130,30 +128,30 @@ in
             type = nullOr (listOf str);
             default = null;
             example = [ "CMD" "pg_isready" ];
-            description = dockerComposeRef "healthcheck";
+            description = serviceRef "healthcheck";
           };
           interval = mkOption {
             type = str;
             default = "30s";
             example = "1m";
-            description = dockerComposeRef "healthcheck";
+            description = serviceRef "healthcheck";
           };
           timeout = mkOption {
             type = str;
             default = "30s";
             example = "10s";
-            description = dockerComposeRef "healthcheck";
+            description = serviceRef "healthcheck";
           };
           start_period = mkOption {
             type = str;
             default = "0s";
             example = "30s";
-            description = dockerComposeRef "healthcheck";
+            description = serviceRef "healthcheck";
           };
           retries = mkOption {
             type = int;
             default = 3;
-            description = dockerComposeRef "healthcheck";
+            description = serviceRef "healthcheck";
           };
         };
       });
@@ -165,14 +163,14 @@ in
         See ${link "https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities"
         "`docker run --device` documentation"}
 
-        ${dockerComposeRef "devices"}
+        ${serviceRef "devices"}
       '';
     };
     service.dns = mkOption {
       type = listOf str;
       default = [];
       example = [ "8.8.8.8" "8.8.4.4" ];
-      description = dockerComposeRef "dns";
+      description = serviceRef "dns";
     };
     service.labels = mkOption {
       type = attrsOf str;
@@ -183,47 +181,53 @@ in
         "traefik.http.routers.my-service.rule" = "Host(`my-service.localhost`)";
         "traefik.http.routers.my-service.entrypoints" = "web";
       };
-      description = dockerComposeRef "labels";
+      description = serviceRef "labels";
     };
     service.links = mkOption {
       type = listOf str;
       default = [];
-      description = dockerComposeRef "links";
+      description = serviceRef "links";
     };
     service.external_links = mkOption {
       type = listOf str;
       default = [];
-      description = dockerComposeRef "external_links";
+      description = serviceRef "external_links";
     };
     service.extra_hosts = mkOption {
       type = listOf str;
       default = [];
-      description = dockerComposeRef "extra_hosts";
+      description = serviceRef "extra_hosts";
     };
     service.working_dir = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeKitchenSink;
+      description = ''
+        ${serviceRef "working_dir"}
+      '';
     };
     service.privileged = mkOption {
       type = nullOr bool;
       default = null;
-      description = dockerComposeKitchenSink;
+      description = ''
+        ${serviceRef "privileged"}
+      '';
     };
     service.entrypoint = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeRef "entrypoint";
+      description = serviceRef "entrypoint";
     };
     service.restart = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeRef "restart";
+      description = serviceRef "restart";
     };
     service.user = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeKitchenSink;
+      description = ''
+        ${serviceRef "user"}
+      '';
     };
     service.ports = mkOption {
       type = listOf types.unspecified;
@@ -231,38 +235,38 @@ in
       description = ''
         Expose ports on host. "host:container" or structured.
 
-        ${dockerComposeRef "ports"}
+        ${serviceRef "ports"}
       '';
     };
     service.expose = mkOption {
       type = listOf str;
       default = [];
-      description = dockerComposeRef "expose";
+      description = serviceRef "expose";
     };
     service.env_file = mkOption {
       type = listOf str;
       default = [];
-      description = dockerComposeRef "env_file";
+      description = serviceRef "env_file";
     };
     service.network_mode = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeRef "network_mode";
+      description = serviceRef "network_mode";
     };
     service.networks = mkOption {
       type = nullOr (listOf types.str);
       default = null;
-      description = dockerComposeRef "networks";
+      description = serviceRef "networks";
     };
     service.stop_signal = mkOption {
       type = nullOr str;
       default = null;
-      description = dockerComposeRef "stop_signal";
+      description = serviceRef "stop_signal";
     };
     service.sysctls = mkOption {
       type = attrsOf (either str int);
       default = {};
-      description = dockerComposeRef "sysctls";
+      description = serviceRef "sysctls";
     };
     service.capabilities = mkOption {
       type = attrsOf (nullOr bool);
@@ -273,13 +277,15 @@ in
 
         Setting a capability to `true` means that it will be
         "added". Setting it to `false` means that it will be "dropped".
-        ${dockerComposeRef "cap_add-cap_drop"}
 
         Omitted and `null` capabilities will therefore be set
         according to Docker's ${
           link "https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities"
                "default list of capabilities."
         }
+
+        ${serviceRef "cap_add"}
+        ${serviceRef "cap_drop"}
       '';
     };
   };