hercules-ci/arion
1
1
Fork 0
mirror of https://github.com/hercules-ci/arion.git synced 2024-11-26 10:05:39 +03:00
Code Issues Projects Releases Wiki Activity

Merge branch 'fix-doc-formatting'

Browse Source
This commit is contained in:
Robert Hensing 2019-10-29 13:02:49 +01:00
commit 77b89cb424
9 changed files with 99 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/modules/ROOT/partials/NixOSOptions.adoc
View File

@ -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]

9
nix/overlay.nix
View File

@ -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";

2
src/nix/modules/service/default-exec.nix
View File

@ -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.
'';
};
};

18
src/nix/modules/service/docker-compose-service.nix
View File

@ -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."

4
src/nix/modules/service/extended-info.nix
View File

@ -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 = {};
};

20
src/nix/modules/service/image.nix
View File

@ -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 {

2
src/nix/modules/service/nixos-init.nix
View File

@ -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.
'';
};
};

8
src/nix/modules/service/nixos.nix
View File

@ -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.
'';
};

9
update-options Executable file
View File

@ -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