From 0a8f8e7fb8254bb7fadd16a9b212d4505f46533b Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 29 Oct 2019 12:52:00 +0100
Subject: [PATCH] Fix doc formatting

---
 docs/modules/ROOT/partials/NixOSOptions.adoc  | 112 +++++++++---------
 nix/overlay.nix                               |   9 +-
 src/nix/modules/service/default-exec.nix      |   2 +-
 .../service/docker-compose-service.nix        |  18 +--
 src/nix/modules/service/extended-info.nix     |   4 +-
 src/nix/modules/service/image.nix             |  20 ++--
 src/nix/modules/service/nixos-init.nix        |   2 +-
 src/nix/modules/service/nixos.nix             |   8 +-
 update-options                                |   9 ++
 9 files changed, 99 insertions(+), 85 deletions(-)
 create mode 100755 update-options

diff --git a/docs/modules/ROOT/partials/NixOSOptions.adoc b/docs/modules/ROOT/partials/NixOSOptions.adoc
index d9f551f..93448fc 100644
--- a/docs/modules/ROOT/partials/NixOSOptions.adoc
+++ b/docs/modules/ROOT/partials/NixOSOptions.adoc
@@ -183,8 +183,8 @@ No Example:: {blank}
 
 A human readable name for the docker image.
 
-Shows up in the <code>docker ps</code> output in the
-<code>IMAGE</code> column, among other places.
+Shows up in the `docker ps` output in the
+`IMAGE` column, among other places.
 
 
 [discrete]
@@ -203,11 +203,11 @@ No Example:: {blank}
 == services.<name>.image.nixBuild
 
 Whether to build this image with Nixpkgs'
-<code>dockerTools.buildLayeredImage</code>
-and then load it with <code>docker load</code>.
+`dockerTools.buildLayeredImage`
+and then load it with `docker load`.
 
-By default, an image will be built with Nix unless <option>service.image</option>
-is set. See also <option>image.name</option>, which defaults to
+By default, an image will be built with Nix unless `service.image`
+is set. See also `image.name`, which defaults to
 the service name.
 
 
@@ -225,11 +225,11 @@ This is a low-level fallback for when a container option has not
 been modeled in the Arion module system.
 
 This attribute set does not have an appropriate merge function.
-Please use the specific <code>image</code> options instead.
+Please use the specific `image` options instead.
 
 Run-time configuration of the container. A full list of the
-options are available at in the <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">Docker Image Specification
-v1.2.0</link>.
+options is available in the https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions[Docker Image Specification
+v1.2.0].
 
 
 [discrete]
@@ -247,11 +247,11 @@ No Example:: {blank}
 
 == services.<name>.nixos.build
 
-NixOS build products from <code>config.system.build</code>, such as <code>toplevel</code> and <code>etc</code>.
+NixOS build products from `config.system.build`, such as `toplevel` and `etc`.
 
 This option is unused by default, because not all images use NixOS.
 
-One way to use this is to enable <code>nixos.useSystemd</code>, but the
+One way to use this is to enable `nixos.useSystemd`, but the
 NixOS configuration can be used in other ways.
 
 
@@ -269,7 +269,7 @@ Modules to add to the NixOS configuration.
 
 This option is unused by default, because not all images use NixOS.
 
-One way to use this is to enable <code>nixos.useSystemd</code>, but the
+One way to use this is to enable `nixos.useSystemd`, but the
 NixOS configuration can be used in other ways.
 
 
@@ -292,7 +292,7 @@ Evaluated NixOS configuration, to be read by service-level modules.
 
 This option is unused by default, because not all images use NixOS.
 
-One way to use this is to enable <code>nixos.useSystemd</code>, but the
+One way to use this is to enable `nixos.useSystemd`, but the
 NixOS configuration can be used in other ways.
 
 
@@ -308,7 +308,7 @@ No Example:: {blank}
 
 When enabled, call the NixOS systemd-based init system.
 
-Configure NixOS with <code>nixos.configuration</code>.
+Configure NixOS with the `nixos.configuration` option.
 
 
 [discrete]
@@ -327,10 +327,10 @@ No Example:: {blank}
 == services.<name>.out.extendedInfo
 
 Information about a service to include in the Docker Compose file,
-but that will not be used by the <code>docker-compose</code> command
+but that will not be used by the `docker-compose`> command
 itself.
 
-It will be inserted in <code>x-arion.serviceInfo.&lt;service.name></code>.
+It will be inserted in `x-arion.serviceInfo.<service.name>`.
 
 
 [discrete]
@@ -348,7 +348,7 @@ No Example:: {blank}
 
 == services.<name>.out.service
 
-Raw input for the service in <code>docker-compose.yaml</code>.
+Raw input for the service in `docker-compose.yaml`.
 
 You should not need to use this option. If anything is
 missing, please contribute the missing option.
@@ -369,7 +369,7 @@ No Example:: {blank}
 
 Locates a Dockerfile to use for creating an image to use in this service.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#context">Docker Compose#context</link>
+See link:https://docs.docker.com/compose/compose-file/#context[Docker Compose#context]
 
 
 [discrete]
@@ -389,12 +389,12 @@ No Example:: {blank}
 
 Enable/disable linux capabilities, or pick Docker's default.
 
-Setting a capability to <code>true</code> means that it will be
-"added". Setting it to <code>false</code> means that it will be "dropped".
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#cap_add-cap_drop">Docker Compose#cap_add-cap_drop</link>
+Setting a capability to `true` means that it will be
+"added". Setting it to `false` means that it will be "dropped".
+See link:https://docs.docker.com/compose/compose-file/#cap_add-cap_drop[Docker Compose#cap_add-cap_drop]
 
-Omitted and <code>null</code> capabilities will therefore be set
-according to Docker's <link xlink:href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">default list of capabilities.</link>
+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.]
 
 
 [discrete]
@@ -417,7 +417,7 @@ Example::
 
 == services.<name>.service.command
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#command">Docker Compose#command</link>
+See link:https://docs.docker.com/compose/compose-file/#command[Docker Compose#command]
 
 [discrete]
 === details
@@ -434,7 +434,7 @@ No Example:: {blank}
 
 == services.<name>.service.container_name
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#container_name">Docker Compose#container_name</link>
+See link:https://docs.docker.com/compose/compose-file/#container_name[Docker Compose#container_name]
 
 [discrete]
 === details
@@ -452,7 +452,7 @@ No Example:: {blank}
 == services.<name>.service.defaultExec
 
 Container program and arguments to invoke when calling
-<code>arion exec &lt;service.name></code> without further arguments.
+`arion exec <service.name>` without further arguments.
 
 
 [discrete]
@@ -470,7 +470,7 @@ No Example:: {blank}
 
 == services.<name>.service.depends_on
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#depends_on">Docker Compose#depends_on</link>
+See link:https://docs.docker.com/compose/compose-file/#depends_on[Docker Compose#depends_on]
 
 [discrete]
 === details
@@ -487,9 +487,9 @@ No Example:: {blank}
 
 == services.<name>.service.devices
 
-See <link xlink:href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities"><code>docker run --device</code> documentation</link>
+See link:https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities[`docker run --device` documentation]
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#devices">Docker Compose#devices</link>
+See link:https://docs.docker.com/compose/compose-file/#devices[Docker Compose#devices]
 
 
 [discrete]
@@ -507,7 +507,7 @@ No Example:: {blank}
 
 == services.<name>.service.entrypoint
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#entrypoint">Docker Compose#entrypoint</link>
+See link:https://docs.docker.com/compose/compose-file/#entrypoint[Docker Compose#entrypoint]
 
 [discrete]
 === details
@@ -524,7 +524,7 @@ No Example:: {blank}
 
 == services.<name>.service.env_file
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#env_file">Docker Compose#env_file</link>
+See link:https://docs.docker.com/compose/compose-file/#env_file[Docker Compose#env_file]
 
 [discrete]
 === details
@@ -541,7 +541,7 @@ No Example:: {blank}
 
 == services.<name>.service.environment
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#environment">Docker Compose#environment</link>
+See link:https://docs.docker.com/compose/compose-file/#environment[Docker Compose#environment]
 
 [discrete]
 === details
@@ -558,7 +558,7 @@ No Example:: {blank}
 
 == services.<name>.service.expose
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#expose">Docker Compose#expose</link>
+See link:https://docs.docker.com/compose/compose-file/#expose[Docker Compose#expose]
 
 [discrete]
 === details
@@ -575,7 +575,7 @@ No Example:: {blank}
 
 == services.<name>.service.external_links
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#external_links">Docker Compose#external_links</link>
+See link:https://docs.docker.com/compose/compose-file/#external_links[Docker Compose#external_links]
 
 [discrete]
 === details
@@ -592,7 +592,7 @@ No Example:: {blank}
 
 == services.<name>.service.extra_hosts
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#extra_hosts">Docker Compose#extra_hosts</link>
+See link:https://docs.docker.com/compose/compose-file/#extra_hosts[Docker Compose#extra_hosts]
 
 [discrete]
 === details
@@ -626,9 +626,9 @@ No Example:: {blank}
 
 == services.<name>.service.hostname
 
-Analogous to the <code>docker run</code> counterpart.
+Analogous to the `docker run` counterpart.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir">Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir</link>
+See link:https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir[Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir]
 
 
 [discrete]
@@ -646,7 +646,7 @@ No Example:: {blank}
 
 == services.<name>.service.image
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#image">Docker Compose#image</link>
+See link:https://docs.docker.com/compose/compose-file/#image[Docker Compose#image]
 
 [discrete]
 === details
@@ -658,7 +658,7 @@ No Example:: {blank}
 
 == services.<name>.service.links
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#links">Docker Compose#links</link>
+See link:https://docs.docker.com/compose/compose-file/#links[Docker Compose#links]
 
 [discrete]
 === details
@@ -675,7 +675,7 @@ No Example:: {blank}
 
 == services.<name>.service.name
 
-The name of the service - <code>&lt;name></code> in the composition-level <code>services.&lt;name></code>
+The name of the service - `<name>` in the composition-level `services.<name>`
 
 
 [discrete]
@@ -688,7 +688,7 @@ No Example:: {blank}
 
 == services.<name>.service.network_mode
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#network_mode">Docker Compose#network_mode</link>
+See link:https://docs.docker.com/compose/compose-file/#network_mode[Docker Compose#network_mode]
 
 [discrete]
 === details
@@ -705,7 +705,7 @@ No Example:: {blank}
 
 == services.<name>.service.networks
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#networks">Docker Compose#networks</link>
+See link:https://docs.docker.com/compose/compose-file/#networks[Docker Compose#networks]
 
 [discrete]
 === details
@@ -724,7 +724,7 @@ No Example:: {blank}
 
 Expose ports on host. "host:container" or structured.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#ports">Docker Compose#ports</link>
+See link:https://docs.docker.com/compose/compose-file/#ports[Docker Compose#ports]
 
 
 [discrete]
@@ -742,9 +742,9 @@ No Example:: {blank}
 
 == services.<name>.service.privileged
 
-Analogous to the <code>docker run</code> counterpart.
+Analogous to the `docker run` counterpart.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir">Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir</link>
+See link:https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir[Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir]
 
 
 [discrete]
@@ -762,7 +762,7 @@ No Example:: {blank}
 
 == services.<name>.service.restart
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#restart">Docker Compose#restart</link>
+See link:https://docs.docker.com/compose/compose-file/#restart[Docker Compose#restart]
 
 [discrete]
 === details
@@ -779,7 +779,7 @@ No Example:: {blank}
 
 == services.<name>.service.stop_signal
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#stop_signal">Docker Compose#stop_signal</link>
+See link:https://docs.docker.com/compose/compose-file/#stop_signal[Docker Compose#stop_signal]
 
 [discrete]
 === details
@@ -796,7 +796,7 @@ No Example:: {blank}
 
 == services.<name>.service.sysctls
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#sysctls">Docker Compose#sysctls</link>
+See link:https://docs.docker.com/compose/compose-file/#sysctls[Docker Compose#sysctls]
 
 [discrete]
 === details
@@ -813,7 +813,7 @@ No Example:: {blank}
 
 == services.<name>.service.tmpfs
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#tmpfs">Docker Compose#tmpfs</link>
+See link:https://docs.docker.com/compose/compose-file/#tmpfs[Docker Compose#tmpfs]
 
 [discrete]
 === details
@@ -830,9 +830,9 @@ No Example:: {blank}
 
 == services.<name>.service.tty
 
-Analogous to the <code>docker run</code> counterpart.
+Analogous to the `docker run` counterpart.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir">Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir</link>
+See link:https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir[Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir]
 
 
 [discrete]
@@ -884,9 +884,9 @@ No Example:: {blank}
 
 == services.<name>.service.user
 
-Analogous to the <code>docker run</code> counterpart.
+Analogous to the `docker run` counterpart.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir">Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir</link>
+See link:https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir[Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir]
 
 
 [discrete]
@@ -904,7 +904,7 @@ No Example:: {blank}
 
 == services.<name>.service.volumes
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#volumes">Docker Compose#volumes</link>
+See link:https://docs.docker.com/compose/compose-file/#volumes[Docker Compose#volumes]
 
 [discrete]
 === details
@@ -921,9 +921,9 @@ No Example:: {blank}
 
 == services.<name>.service.working_dir
 
-Analogous to the <code>docker run</code> counterpart.
+Analogous to the `docker run` counterpart.
 
-See <link xlink:href="https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir">Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir</link>
+See link:https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir[Docker Compose#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir]
 
 
 [discrete]
diff --git a/nix/overlay.nix b/nix/overlay.nix
index b058f58..6dd297e 100644
--- a/nix/overlay.nix
+++ b/nix/overlay.nix
@@ -19,8 +19,13 @@ in
 
   doc-options = import ../docs/options.nix {};
   doc-options-check = self.runCommand "doc-options-check" {} ''
-    diff --color -u ${../docs/modules/ROOT/partials/NixOSOptions.adoc} ${self.doc-options}
-    touch $out
+    if diff --color -u ${../docs/modules/ROOT/partials/NixOSOptions.adoc} ${self.doc-options}; then
+      touch $out
+    else
+      echo 1>&2 "The doc options have changed and need to be added."
+      echo 1>&2 "Please run ./update-options in the root of your arion clone."
+      exit 1
+    fi
   '';
   doc = self.stdenv.mkDerivation { 
     name = "arion-documentation"; 
diff --git a/src/nix/modules/service/default-exec.nix b/src/nix/modules/service/default-exec.nix
index d3c31b3..0c2b0f0 100644
--- a/src/nix/modules/service/default-exec.nix
+++ b/src/nix/modules/service/default-exec.nix
@@ -9,7 +9,7 @@ in
       default = ["/bin/sh"];
       description = ''
         Container program and arguments to invoke when calling
-        <code>arion exec &lt;service.name></code> without further arguments.
+        `arion exec <service.name>` without further arguments.
       '';
     };
   };
diff --git a/src/nix/modules/service/docker-compose-service.nix b/src/nix/modules/service/docker-compose-service.nix
index 0451b78..42cd89f 100644
--- a/src/nix/modules/service/docker-compose-service.nix
+++ b/src/nix/modules/service/docker-compose-service.nix
@@ -11,11 +11,11 @@ let
   inherit (types) listOf nullOr attrsOf str either int bool;
 
   link = url: text:
-    ''<link xlink:href="${url}">${text}</link>'';
+    ''link:${url}[${text}]'';
   dockerComposeRef = fragment:
-    ''See <link xlink:href="https://docs.docker.com/compose/compose-file/#${fragment}">Docker Compose#${fragment}</link>'';
+    ''See ${link "https://docs.docker.com/compose/compose-file/#${fragment}" "Docker Compose#${fragment}"}'';
   dockerComposeKitchenSink = ''
-    Analogous to the <code>docker run</code> counterpart.
+    Analogous to the `docker run` counterpart.
 
     ${dockerComposeRef "domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir"}
   '';
@@ -33,7 +33,7 @@ in
     out.service = mkOption {
       type = attrsOf types.unspecified;
       description = ''
-        Raw input for the service in <code>docker-compose.yaml</code>.
+        Raw input for the service in `docker-compose.yaml`.
 
         You should not need to use this option. If anything is
         missing, please contribute the missing option.
@@ -47,7 +47,7 @@ in
     service.name = mkOption {
       type = str;
       description = ''
-        The name of the service - <code>&lt;name></code> in the composition-level <code>services.&lt;name></code>
+        The name of the service - `<name>` in the composition-level `services.<name>`
       '';
       readOnly = true;
     };
@@ -110,7 +110,7 @@ in
       default = [];
       description = ''
         See ${link "https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities"
-        "<code>docker run --device</code> documentation"}
+        "`docker run --device` documentation"}
 
         ${dockerComposeRef "devices"}
       '';
@@ -201,11 +201,11 @@ in
       description = ''
         Enable/disable linux capabilities, or pick Docker's default.
 
-        Setting a capability to <code>true</code> means that it will be
-        "added". Setting it to <code>false</code> means that it will be "dropped".
+        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 <code>null</code> capabilities will therefore be set
+        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."
diff --git a/src/nix/modules/service/extended-info.nix b/src/nix/modules/service/extended-info.nix
index c6a35f0..7d14a59 100644
--- a/src/nix/modules/service/extended-info.nix
+++ b/src/nix/modules/service/extended-info.nix
@@ -12,10 +12,10 @@ in
       type = attrsOf unspecified;
       description = ''
         Information about a service to include in the Docker Compose file,
-        but that will not be used by the <code>docker-compose</code> command
+        but that will not be used by the `docker-compose`> command
         itself.
 
-        It will be inserted in <code>x-arion.serviceInfo.&lt;service.name></code>.
+        It will be inserted in `x-arion.serviceInfo.<service.name>`.
       '';
       default = {};
     };
diff --git a/src/nix/modules/service/image.nix b/src/nix/modules/service/image.nix
index a3b91b5..88b75d2 100644
--- a/src/nix/modules/service/image.nix
+++ b/src/nix/modules/service/image.nix
@@ -40,7 +40,7 @@ in
     build.image = mkOption {
       type = nullOr package;
       description = ''
-        Docker image derivation to be <code>docker load</code>ed.
+        Docker image derivation to be `docker load`ed.
       '';
       internal = true;
     };
@@ -58,11 +58,11 @@ in
       type = bool;
       description = ''
         Whether to build this image with Nixpkgs'
-        <code>dockerTools.buildLayeredImage</code>
-        and then load it with <code>docker load</code>.
+        `dockerTools.buildLayeredImage`
+        and then load it with `docker load`.
 
-        By default, an image will be built with Nix unless <option>service.image</option>
-        is set. See also <option>image.name</option>, which defaults to
+        By default, an image will be built with Nix unless `service.image`
+        is set. See also `image.name`, which defaults to
         the service name.
       '';
     };
@@ -73,8 +73,8 @@ in
       description = ''
         A human readable name for the docker image.
 
-        Shows up in the <code>docker ps</code> output in the
-        <code>IMAGE</code> column, among other places.
+        Shows up in the `docker ps` output in the
+        `IMAGE` column, among other places.
       '';
     };
     image.contents = mkOption {
@@ -92,11 +92,11 @@ in
         been modeled in the Arion module system.
 
         This attribute set does not have an appropriate merge function.
-        Please use the specific <code>image</code> options instead.
+        Please use the specific `image` options instead.
 
         Run-time configuration of the container. A full list of the
-        options are available at in the <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">Docker Image Specification
-        v1.2.0</link>.
+        options is available in the https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions[Docker Image Specification
+        v1.2.0].
       '';
     };
     image.command = mkOption {
diff --git a/src/nix/modules/service/nixos-init.nix b/src/nix/modules/service/nixos-init.nix
index 5e97451..d152f0c 100644
--- a/src/nix/modules/service/nixos-init.nix
+++ b/src/nix/modules/service/nixos-init.nix
@@ -13,7 +13,7 @@ in
       description = ''
         When enabled, call the NixOS systemd-based init system.
 
-        Configure NixOS with <code>nixos.configuration</code>.
+        Configure NixOS with the `nixos.configuration` option.
       '';
     };
   };
diff --git a/src/nix/modules/service/nixos.nix b/src/nix/modules/service/nixos.nix
index 2cfc344..6639645 100644
--- a/src/nix/modules/service/nixos.nix
+++ b/src/nix/modules/service/nixos.nix
@@ -18,7 +18,7 @@ in
 
         This option is unused by default, because not all images use NixOS.
 
-        One way to use this is to enable <code>nixos.useSystemd</code>, but the
+        One way to use this is to enable `nixos.useSystemd`, but the
         NixOS configuration can be used in other ways.
       '';
     };
@@ -27,11 +27,11 @@ in
       type = attrs;
       readOnly = true;
       description = ''
-        NixOS build products from <code>config.system.build</code>, such as <code>toplevel</code> and <code>etc</code>.
+        NixOS build products from `config.system.build`, such as `toplevel` and `etc`.
 
         This option is unused by default, because not all images use NixOS.
 
-        One way to use this is to enable <code>nixos.useSystemd</code>, but the
+        One way to use this is to enable `nixos.useSystemd`, but the
         NixOS configuration can be used in other ways.
       '';
     };
@@ -44,7 +44,7 @@ in
 
         This option is unused by default, because not all images use NixOS.
 
-        One way to use this is to enable <code>nixos.useSystemd</code>, but the
+        One way to use this is to enable `nixos.useSystemd`, but the
         NixOS configuration can be used in other ways.
       '';
     };
diff --git a/update-options b/update-options
new file mode 100755
index 0000000..14a66e9
--- /dev/null
+++ b/update-options
@@ -0,0 +1,9 @@
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash
+
+set -eu -o pipefail
+
+cd "$(dirname ${BASH_SOURCE[0]})"
+
+doc_options="$(nix-build nix -A doc-options)"
+cat "$doc_options" >docs/modules/ROOT/partials/NixOSOptions.adoc