doc/manual: Switch to asciidoctor and other improvements

See https://github.com/hercules-ci/arion/issues/10

doc/default.nix

@@ -0,0 +1,8 @@
+{ pkgs ? import ../nix {} }:
+let
+  inherit (pkgs) recurseIntoAttrs callPackage;
+in
+
+recurseIntoAttrs {
+  manual = callPackage ./manual {};
+}

doc/manual/.gitignore

@@ -0,0 +1,4 @@
+introduction.xml
+manual.html
+options-composition.xml
+options-service.xml

doc/manual/Makefile

@@ -0,0 +1,37 @@
+xsltproc = xsltproc --nonet \
+ --param section.autolabel 0 \
+ --param section.label.includes.component.label 0 \
+ --param chapter.autolabel 0 \
+ --param chapter.label.includes.component.label 0 \
+ --param appendix.autolabel 0 \
+ --param appendix.label.includes.component.label 0 \
+ --param generate.toc "'book toc,title chapter nop section nop sect1 nop sect2 nop sect3 nop sect4 nop sect5 nop'" \
+ --param html.stylesheet \'style.css\' \
+ --param xref.with.number.and.title 0 \
+ --param toc.section.depth 3 \
+ --param admon.style \'\' \
+ --param callout.graphics.extension \'.gif\' \
+ --param contrib.inline.enabled 0
+
+docbookxsl = http://docbook.sourceforge.net/release/xsl/current
+
+all: manual.html
+
+manual.html: manual.xml introduction.xml options-composition.xml options-service.xml
+	$(xsltproc) --xinclude --stringparam profile.condition manual \
+	  $(docbookxsl)/profiling/profile.xsl manual.xml | \
+	  $(xsltproc) --output manual.html $(docbookxsl)/xhtml/docbook.xsl -
+
+# -e 's_<book lang="en">__' -e 's_</book>__'
+%.xml: %.asciidoc
+	asciidoctor --backend docbook45 --doctype article $<
+	sed -e 's/<!DOCTYPE.*//' -e 's/<?asciidoc-toc?>//' -i $@
+	cat $@
+
+options-composition.xml options-service.xml:
+	@if test -z '$(generatedDocBook)'; then echo "generatedDocBook env var is required. Are you running in 'nix-shell -A manual'?"; exit 1; fi
+	cp $(generatedDocBook)/* .
+
+install: all
+	mkdir -p $(docdir)
+	cp manual.html style.css $(docdir)

doc/manual/default.nix

@@ -0,0 +1,117 @@
+{ pkgs ? import ../../nix {}, version ? "local" }:
+let
+  inherit (pkgs) recurseIntoAttrs callPackage runCommand lib stdenv ;
+
+  nixosManualPath = s: "${pkgs.path}/nixos/doc/manual/${s}";
+
+  # NixOS module system options in JSON format.
+  options = { moduleType, description, optionsList }: recurseIntoAttrs rec {
+    optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList);
+
+    optionsDocBook = runCommand "options-db.xml" {} ''
+      optionsXML=${optionsXML}
+      if grep /nixpkgs/nixos/modules $optionsXML; then
+        echo "The manual appears to depend on the location of Nixpkgs, which is bad"
+        echo "since this prevents sharing via the NixOS channel.  This is typically"
+        echo "caused by an option default that refers to a relative path (see above"
+        echo "for hints about the offending path)."
+        exit 1
+      fi
+      ${pkgs.buildPackages.libxslt.bin}/bin/xsltproc \
+        --stringparam revision '${version}' \
+        --stringparam sourceUrl 'https://github.com/hercules-ci/arion/blob/${version}' \
+        -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML
+      ${pkgs.buildPackages.libxslt.bin}/bin/xsltproc \
+        -o "$out" ${nixosManualPath "postprocess-option-descriptions.xsl"} intermediate.xml
+    '';
+    
+    optionsJSON = runCommand "${moduleType}-options-json" {
+      meta.description = description;
+    } ''
+      # Export list of options in different format.
+      dst=$out/share/doc/arion
+      mkdir -p $dst
+
+      cp ${builtins.toFile "options-${moduleType}.json" (builtins.unsafeDiscardStringContext (builtins.toJSON
+        (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList))))
+      } $dst/options-${moduleType}.json
+
+      mkdir -p $out/nix-support
+      echo "file json $dst/options-${moduleType}.json" >> $out/nix-support/hydra-build-products
+    '';
+
+    
+  };
+
+  fixPaths = opt: opt // builtins.trace opt.declarations {
+    declarations = map (d: lib.strings.removePrefix "/" (lib.strings.removePrefix (toString ../..) (toString d))) opt.declarations;
+  };
+
+in
+
+recurseIntoAttrs rec {
+  compositionOptions = options {
+    moduleType = "composition";
+    description = "List of Arion composition-level options in JSON format";
+    optionsList = let composition = import ../../src/nix/eval-composition.nix { inherit pkgs; };
+                  in map fixPaths (lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList composition.options));
+  };
+  serviceOptions = options {
+    moduleType = "service";
+    description = "List of Arion service-level options in JSON format";
+    optionsList = let service = pkgs.callPackage ../../src/nix/eval-service.nix {} { modules = []; uid = -1; };
+                  in map fixPaths (lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList service.options));
+  };
+  generatedDocBook = runCommand "generated-docbook" {} ''
+    mkdir $out
+    ln -s ${compositionOptions.optionsDocBook} $out/options-composition.xml
+    ln -s ${serviceOptions.optionsDocBook} $out/options-service.xml
+  '';
+  manual = stdenv.mkDerivation {
+    src = lib.sourceByRegex ./. [
+      "Makefile$"
+      ".*\.asciidoc$"
+      ".*\.xsl$"
+      ".*\.css$"
+      "^manual.xml$"
+      "^manual.xml$"
+    ];
+    name = "arion-manual";
+    version = version;
+    buildInputs = [
+      (pkgs.libxslt.bin or pkgs.libxslt)
+      pkgs.asciidoctor
+    ];
+    XML_CATALOG_FILES = "${pkgs.docbook_xsl}/xml/xsl/docbook/catalog.xml";
+    inherit generatedDocBook;
+    configurePhase = ''
+      export docdir=$out/doc
+    '';
+    postPatch = ''
+      substituteInPlace manual.xml --subst-var version
+    '';
+    prePatch = ''
+      set -x
+      cp ${generatedDocBook}/* .
+      substituteInPlace options-service.xml \
+        --replace 'xml:id="appendix-configuration-options"' 'xml:id="appendix-service-options"' \
+        --replace '<title>Configuration Options</title>' '<title>Service Options</title>' \
+        --replace 'xml:id="configuration-variable-list"' 'xml:id="service-variable-list"' \
+        ;
+      substituteInPlace options-composition.xml \
+        --replace 'xml:id="appendix-configuration-options"' 'xml:id="appendix-composition-options"' \
+        --replace '<title>Configuration Options</title>' '<title>Composition Options</title>' \
+        --replace 'xml:id="configuration-variable-list"' 'xml:id="composition-variable-list"' \
+        ;
+      ls -R
+      set +x
+    '';
+    shellHook = ''
+      live-build() {
+        inotifywait -e MODIFY -m -r . | while read; do
+          make
+        done
+      }
+    '';
+  };
+}

doc/manual/introduction.asciidoc

@@ -0,0 +1,34 @@
+
+Introduction
+------------
+
+Arion is a tool for building and running applications that
+consist of multiple docker containers. It has special support
+for docker images that are built with Nix, for a smooth
+development experience and improved performance.
+
+It is built on top of https://docs.docker.com/compose/overview/[Docker
+Compose], which implements the container orchestration functionality.
+
+Instead of configuring the compositions in YAML files like
+`docker-compose.yaml`, Arion uses the https://nixos.org/nix/[Nix]
+language to declare the compositions. Because of this, Arion gives you
+the ability to declare your deployments, configuration and packaging
+in the same language. By replacing multiple tools with a single
+language, you decrease your mental load and you can more easily
+refactor and maintain your configurations.
+
+Although Arion can be used as a Docker Compose with an improved
+configuration front end, there is more to be gained from integrating
+with Nix. In particular, the more structured approach of Nix compared
+to Dockerfiles allows the following:
+
+ * Build components of your image in _parallel, automatically_.
+ * Share packages between images, regardless of the order they were
+   added.
+ * Improve performance by _skipping_ container
+   image creation.
+ * Work with _structured data_ instead of strings,
+   templates and a multitude of expression languages.
+ * Refactor across deployments, configuration and
+   packaging.

doc/manual/live-build

@@ -0,0 +1,3 @@
+#!/usr/bin/env nix-shell
+#!nix-shell -A manual
+#!nix-shell --run live-build

doc/manual/manual.xml

@@ -0,0 +1,52 @@
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <info>
+
+    <title>Arion Manual</title>
+    <subtitle>Version @version@</subtitle>
+
+    <author>
+      <affiliation>
+        <orgname>Hercules Labs</orgname>
+      </affiliation>
+      <contrib>Author</contrib>
+    </author>
+
+  </info>
+
+  <xi:include href="introduction.xml" xpointer="xpointer(/article/section)" />
+
+  <chapter>
+    <title>Installation</title>
+    <section>
+      <title>Traditional Linux or Mac</title>
+      <para>
+        TODO: describe: install Nix and nix-env -i
+      </para>
+    </section>
+    <section>
+      <title>Not installing: use it in a project</title>
+      <para>
+        TODO: describe: using nix-shell or in a script, building
+                        images as part of nix-build, pinning,
+                        see also todomvc-nix.
+      </para>
+    </section>
+    <section>
+      <title>NixOS</title>
+      <para>
+        TODO: describe: Docker + environment.systemPackages
+      </para>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>Getting Started</title>
+  </chapter>
+
+  <xi:include href="options-composition.xml" />
+  <xi:include href="options-service.xml" />
+
+</book>

doc/manual/options-to-docbook.xsl

@@ -0,0 +1,224 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:str="http://exslt.org/strings"
+                xmlns:xlink="http://www.w3.org/1999/xlink"
+                xmlns:nixos="tag:nixos.org"
+                xmlns="http://docbook.org/ns/docbook"
+                extension-element-prefixes="str"
+                >
+
+  <xsl:output method='xml' encoding="UTF-8" />
+
+  <xsl:param name="revision" />
+  <xsl:param name="program" />
+  <xsl:param name="sourceUrl" />
+  <xsl:param name="nixPathKey" />
+
+  <xsl:template match="/expr/list">
+    <appendix xml:id="appendix-configuration-options">
+      <title>Configuration Options</title>
+      <variablelist xml:id="configuration-variable-list">
+        <xsl:for-each select="attrs">
+          <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '&lt;', '_'), '>', '_'), '?', '_'))" />
+          <varlistentry>
+            <term xlink:href="#{$id}">
+              <xsl:attribute name="xml:id"><xsl:value-of select="$id"/></xsl:attribute>
+              <option>
+                <xsl:value-of select="attr[@name = 'name']/string/@value" />
+              </option>
+            </term>
+
+            <listitem>
+
+              <nixos:option-description>
+                <para>
+                  <xsl:value-of disable-output-escaping="yes"
+                                select="attr[@name = 'description']/string/@value" />
+                </para>
+              </nixos:option-description>
+
+              <xsl:if test="attr[@name = 'type']">
+                <para>
+                  <emphasis>Type:</emphasis>
+                  <xsl:text> </xsl:text>
+                  <xsl:value-of select="attr[@name = 'type']/string/@value"/>
+                  <xsl:if test="attr[@name = 'readOnly']/bool/@value = 'true'">
+                    <xsl:text> </xsl:text>
+                    <emphasis>(read only)</emphasis>
+                  </xsl:if>
+                </para>
+              </xsl:if>
+
+              <xsl:if test="attr[@name = 'default']">
+                <para>
+                  <emphasis>Default:</emphasis>
+                  <xsl:text> </xsl:text>
+                  <xsl:apply-templates select="attr[@name = 'default']" mode="top" />
+                </para>
+              </xsl:if>
+
+              <xsl:if test="attr[@name = 'example']">
+                <para>
+                  <emphasis>Example:</emphasis>
+                  <xsl:text> </xsl:text>
+                  <xsl:choose>
+                    <xsl:when test="attr[@name = 'example']/attrs[attr[@name = '_type' and string[@value = 'literalExample']]]">
+                      <programlisting><xsl:value-of select="attr[@name = 'example']/attrs/attr[@name = 'text']/string/@value" /></programlisting>
+                    </xsl:when>
+                    <xsl:otherwise>
+                      <xsl:apply-templates select="attr[@name = 'example']" mode="top" />
+                    </xsl:otherwise>
+                  </xsl:choose>
+                </para>
+              </xsl:if>
+
+              <xsl:if test="attr[@name = 'relatedPackages']">
+                <para>
+                  <emphasis>Related packages:</emphasis>
+                  <xsl:text> </xsl:text>
+                  <xsl:value-of disable-output-escaping="yes"
+                                select="attr[@name = 'relatedPackages']/string/@value" />
+                </para>
+              </xsl:if>
+
+              <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0">
+                <para>
+                  <emphasis>Declared by:</emphasis>
+                </para>
+                <xsl:apply-templates select="attr[@name = 'declarations']" />
+              </xsl:if>
+
+              <xsl:if test="count(attr[@name = 'definitions']/list/*) != 0">
+                <para>
+                  <emphasis>Defined by:</emphasis>
+                </para>
+                <xsl:apply-templates select="attr[@name = 'definitions']" />
+              </xsl:if>
+
+            </listitem>
+
+          </varlistentry>
+
+        </xsl:for-each>
+
+      </variablelist>
+    </appendix>
+  </xsl:template>
+
+
+  <xsl:template match="*" mode="top">
+    <xsl:choose>
+      <xsl:when test="string[contains(@value, '&#010;')]">
+<programlisting>
+<xsl:text>''
+</xsl:text><xsl:value-of select='str:replace(string/@value, "${", "&apos;&apos;${")' /><xsl:text>''</xsl:text></programlisting>
+      </xsl:when>
+      <xsl:otherwise>
+        <literal><xsl:apply-templates /></literal>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+
+  <xsl:template match="null">
+    <xsl:text>null</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="string">
+    <xsl:choose>
+      <xsl:when test="(contains(@value, '&quot;') or contains(@value, '\')) and not(contains(@value, '&#010;'))">
+        <xsl:text>''</xsl:text><xsl:value-of select='str:replace(@value, "${", "&apos;&apos;${")' /><xsl:text>''</xsl:text>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>"</xsl:text><xsl:value-of select="str:replace(str:replace(str:replace(str:replace(@value, '\', '\\'), '&quot;', '\&quot;'), '&#010;', '\n'), '$', '\$')" /><xsl:text>"</xsl:text>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+
+  <xsl:template match="int">
+    <xsl:value-of select="@value" />
+  </xsl:template>
+
+
+  <xsl:template match="bool[@value = 'true']">
+    <xsl:text>true</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="bool[@value = 'false']">
+    <xsl:text>false</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="list">
+    [
+    <xsl:for-each select="*">
+      <xsl:apply-templates select="." />
+      <xsl:text> </xsl:text>
+    </xsl:for-each>
+    ]
+  </xsl:template>
+
+
+  <xsl:template match="attrs[attr[@name = '_type' and string[@value = 'literalExample']]]">
+    <xsl:value-of select="attr[@name = 'text']/string/@value" />
+  </xsl:template>
+
+
+  <xsl:template match="attrs">
+    {
+    <xsl:for-each select="attr">
+      <xsl:value-of select="@name" />
+      <xsl:text> = </xsl:text>
+      <xsl:apply-templates select="*" /><xsl:text>; </xsl:text>
+    </xsl:for-each>
+    }
+  </xsl:template>
+
+
+  <xsl:template match="derivation">
+    <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable>
+  </xsl:template>
+
+  <xsl:template match="attr[@name = 'declarations' or @name = 'definitions']">
+    <simplelist>
+      <xsl:for-each select="list/string">
+        <member><filename>
+          <!-- Hyperlink the filename either to the NixOS Subversion
+          repository (if it’s a module and we have a revision number),
+          or to the local filesystem. -->
+          <xsl:choose>
+            <xsl:when test="not(starts-with(@value, '/'))">
+              <xsl:attribute name="xlink:href"><xsl:value-of select="$sourceUrl"/>/<xsl:value-of select="@value"/></xsl:attribute>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:attribute name="xlink:href">file://<xsl:value-of select="@value"/></xsl:attribute>
+            </xsl:otherwise>
+          </xsl:choose>
+          <!-- Print the filename and make it user-friendly by replacing the
+          /nix/store/<hash> prefix by the default location of nixos
+          sources. -->
+          <xsl:choose>
+            <xsl:when test="$nixPathKey != ''">
+              &lt;<xsl:value-of select="$nixPathKey"/>/<xsl:value-of select="@value"/>&gt;
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="@value" />
+            </xsl:otherwise>
+          </xsl:choose>
+        </filename></member>
+      </xsl:for-each>
+    </simplelist>
+  </xsl:template>
+
+
+  <xsl:template match="function">
+    <xsl:text>λ</xsl:text>
+  </xsl:template>
+
+
+</xsl:stylesheet>

doc/manual/preview.html

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Arion Manual</title><link rel="stylesheet" type="text/css" href="style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /></head><body><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="idm140737317696320"></a>Arion Manual</h1></div><div><h2 class="subtitle">Version unreleased</h2></div><div><div class="author"><h3 class="author"></h3><div class="affiliation"><span class="orgname">Hercules Labs<br /></span></div></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#_introduction">Introduction</a></span></dt><dt><span class="chapter"><a href="#idm140737317847200">Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#idm140737317846432">Traditional Linux or Mac</a></span></dt><dt><span class="section"><a href="#idm140737317845056">Not installing: use it in a project</a></span></dt><dt><span class="section"><a href="#idm140737317671792">NixOS</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm140737317670384">Getting Started</a></span></dt><dt><span class="appendix"><a href="#appendix-composition-options">Composition Options</a></span></dt><dt><span class="appendix"><a href="#appendix-service-options">Service Options</a></span></dt></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_introduction"></a>Introduction</h1></div></div></div><p>Arion is a tool for building and running applications that
+consist of multiple docker containers. It has special support
+for docker images that are built with Nix, for a smooth
+development experience and improved performance.</p><p>It is built on top of <a class="ulink" href="https://docs.docker.com/compose/overview/" target="_top">Docker
+Compose</a>, which implements the container orchestration functionality.</p><p>Instead of configuring the compositions in YAML files like
+<code class="literal">docker-compose.yaml</code>, Arion uses the <a class="ulink" href="https://nixos.org/nix/" target="_top">Nix</a>
+language to declare the compositions. Because of this, Arion gives you
+the ability to declare your deployments, configuration and packaging
+in the same language. By replacing multiple tools with a single
+language, you decrease your mental load and you can more easily
+refactor and maintain your configurations.</p><p>Although Arion can be used as a Docker Compose with an improved
+configuration front end, there is more to be gained from integrating
+with Nix. In particular, the more structured approach of Nix compared
+to Dockerfiles allows the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+Build components of your image in <span class="emphasis"><em>parallel, automatically</em></span>.
+</li><li class="listitem">
+Share packages between images, regardless of the order they were
+   added.
+</li><li class="listitem">
+Improve performance by <span class="emphasis"><em>skipping</em></span> container
+   image creation.
+</li><li class="listitem">
+Work with <span class="emphasis"><em>structured data</em></span> instead of strings,
+   templates and a multitude of expression languages.
+</li><li class="listitem">
+Use one language and refactor across deployments, configuration and
+   packaging.
+</li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm140737317847200"></a>Installation</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm140737317846432"></a>Traditional Linux or Mac</h2></div></div></div><p>
+        TODO: describe: install Nix and nix-env -i
+      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm140737317845056"></a>Not installing: use it in a project</h2></div></div></div><p>
+        TODO: describe: using nix-shell or in a script, building
+                        images as part of nix-build, pinning,
+                        see also todomvc-nix.
+      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm140737317671792"></a>NixOS</h2></div></div></div><p>
+        TODO: describe: Docker + environment.systemPackages
+      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm140737317670384"></a>Getting Started</h1></div></div></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix-composition-options"></a>Composition Options</h1></div></div></div><div class="variablelist"><a id="composition-variable-list"></a><dl class="variablelist"><dt><span class="term"><a id="opt-build.dockerComposeYaml"></a><a class="term" href="#opt-build.dockerComposeYaml"><code class="option">build.dockerComposeYaml</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> package</p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/docker-compose-module.nix" target="_top">src/nix/docker-compose-module.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-build.dockerComposeYamlText"></a><a class="term" href="#opt-build.dockerComposeYamlText"><code class="option">build.dockerComposeYamlText</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> Concatenated string</p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/docker-compose-module.nix" target="_top">src/nix/docker-compose-module.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-docker-compose.raw"></a><a class="term" href="#opt-docker-compose.raw"><code class="option">docker-compose.raw</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> attribute set</p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/docker-compose-module.nix" target="_top">src/nix/docker-compose-module.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-docker-compose.services"></a><a class="term" href="#opt-docker-compose.services"><code class="option">docker-compose.services</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> attribute set of list of unspecifieds or unspecified convertible to its</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    {
+    
+    }
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/docker-compose-module.nix" target="_top">src/nix/docker-compose-module.nix</a></code></td></tr></table></dd></dl></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix-service-options"></a>Service Options</h1></div></div></div><div class="variablelist"><a id="service-variable-list"></a><dl class="variablelist"><dt><span class="term"><a id="opt-build.service"></a><a class="term" href="#opt-build.service"><code class="option">build.service</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> attribute set of unspecifieds</p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.build.context"></a><a class="term" href="#opt-service.build.context"><code class="option">service.build.context</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> null or Concatenated string</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        null
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.command"></a><a class="term" href="#opt-service.command"><code class="option">service.command</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> null or unspecified</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        null
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.depends_on"></a><a class="term" href="#opt-service.depends_on"><code class="option">service.depends_on</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> list of Concatenated strings</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    [
+    
+    ]
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.entrypoint"></a><a class="term" href="#opt-service.entrypoint"><code class="option">service.entrypoint</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> null or Concatenated string</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        null
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.environment"></a><a class="term" href="#opt-service.environment"><code class="option">service.environment</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> attribute set of Concatenated string or signed integers</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    {
+    
+    }
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.expose"></a><a class="term" href="#opt-service.expose"><code class="option">service.expose</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> list of Concatenated strings</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    [
+    
+    ]
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.image"></a><a class="term" href="#opt-service.image"><code class="option">service.image</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> Concatenated string</p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.ports"></a><a class="term" href="#opt-service.ports"><code class="option">service.ports</code></a></span></dt><dd><p>Expose ports on host. "host:container" or structured.
+See https://docs.docker.com/compose/compose-file/#ports
+</p><p><span class="emphasis"><em>Type:</em></span> list of unspecifieds</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    [
+    
+    ]
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.restart"></a><a class="term" href="#opt-service.restart"><code class="option">service.restart</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> null or Concatenated string</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        null
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.useHostStore"></a><a class="term" href="#opt-service.useHostStore"><code class="option">service.useHostStore</code></a></span></dt><dd><p>Bind mounts the host store if enabled, avoiding copying.</p><p><span class="emphasis"><em>Type:</em></span> boolean</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        false
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service-host-store.nix" target="_top">src/nix/service-host-store.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.volumes"></a><a class="term" href="#opt-service.volumes"><code class="option">service.volumes</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> list of unspecifieds</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        
+    [
+    
+    ]
+  
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd><dt><span class="term"><a id="opt-service.working_dir"></a><a class="term" href="#opt-service.working_dir"><code class="option">service.working_dir</code></a></span></dt><dd><p></p><p><span class="emphasis"><em>Type:</em></span> null or Concatenated string</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">
+        null
+      </code></p><p><span class="emphasis"><em>Declared by:</em></span></p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="filename"><a class="filename" href="https://github.com/hercules-ci/arion/blob/unreleased/src/nix/service.nix" target="_top">src/nix/service.nix</a></code></td></tr></table></dd></dl></div></div></div></body></html>

doc/manual/style.css

@@ -0,0 +1,159 @@
+
+hr { color: #ddd; margin-top: 3ex; }
+h1, h2, h3, h4 { font-weight: bold; }
+h1 { font-size: 200%; margin-top: 5ex; }
+h2 { font-size: 160%; margin-top: 4ex; }
+h3,h4 { font-size: 120%; margin-top: 3ex; }
+
+/* From Semantic UI */
+body {
+  font-family: Lato,'Helvetica Neue',Arial,Helvetica,sans-serif;
+  font-size: 14px;
+  line-height: 1.4285em;
+  color: rgba(0,0,0,.87);
+}
+
+code.literal {
+    background-color: #f7f7f7;
+}
+
+a {
+ background-color:transparent;
+ -webkit-text-decoration-skip:objects
+}
+a {
+ color:#4183c4;
+ text-decoration:none
+}
+a:hover {
+ color:#1e70bf;
+ text-decoration:none
+}
+::-webkit-selection {
+ background-color:#cce2ff;
+ color:rgba(0,0,0,.87)
+}
+::-moz-selection {
+ background-color:#cce2ff;
+ color:rgba(0,0,0,.87)
+}
+::selection {
+ background-color:#cce2ff;
+ color:rgba(0,0,0,.87)
+}
+
+/* toc menu */
+@media screen and (min-width: 60em) {
+  body {
+    margin-left: 16.5em; 
+  }
+  div.toc {
+    position: fixed;
+    top: 0pt;
+    left: 1em;
+    height: 100%;
+    overflow-y: auto;
+    width: 15.5em;
+  }
+}
+@media screen and (min-width: 90em) {
+  div.toc {
+    left: 5em;
+  }
+}
+/* hide per chapter toc */
+div.chapter div.toc {
+    display: none;
+}
+
+
+/* From Nixpkgs: */
+
+div.book
+{
+    text-align: center;
+}
+
+div.book > div
+{
+    /*
+     * based on https://medium.com/@zkareemz/golden-ratio-62b3b6d4282a
+     * we do 70 characters per line to fit code listings better
+     * 70 * (font-size / 1.618)
+     * expression for emacs:
+     * (* 70 (/ 1 1.618))
+     */
+    max-width: 43.2em;
+    text-align: left;
+    margin: auto;
+}
+
+
+/***************************************************************************
+                               Special elements:
+ ***************************************************************************/
+
+.term
+{
+    font-weight: bold;
+
+}
+
+div.variablelist dd p, div.glosslist dd p
+{
+    margin-top: 0em;
+}
+
+div.variablelist dd, div.glosslist dd
+{
+    margin-left: 1.5em;
+}
+
+div.glosslist dt
+{
+    font-style: italic;
+}
+
+.varname
+{
+    color: #004000;
+}
+
+span.command strong
+{
+    font-weight: normal;
+    color: #004000;
+}
+
+div.calloutlist table
+{
+    box-shadow: none;
+}
+
+table
+{
+    border-collapse: collapse;
+    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
+}
+
+table.simplelist
+{
+    text-align: left;
+    color: #005aa0;
+    border: 0;
+    padding: 5px;
+    background: #fffff5;
+    font-weight: normal;
+    font-style: italic;
+    box-shadow: none;
+    margin-bottom: 1em;
+}
+
+div.navheader table, div.navfooter table {
+    box-shadow: none;
+}
+
+div.affiliation
+{
+    font-style: italic;
+}

nix/overlay.nix

@@ -1,4 +1,5 @@
 self: super: {
   arion = super.callPackage ../arion.nix {};
   tests = super.callPackage ../tests {};
+  doc = super.callPackage ../doc {};
 }

src/nix/docker-compose-module.nix

@@ -12,44 +12,27 @@
 { pkgs, uid, lib, config, ... }:
 
 let
-  evalService = name: modules:
-    let
-      composite = lib.evalModules {
-        check = true;
-        modules = builtinModules ++ modules;
-      };
-
-      builtinModules = [
-        argsModule
-        ./service.nix
-        ./service-host-store.nix
-      ];
-
-      argsModule = {
-        _file = ./docker-compose-module.nix;
-        key = ./docker-compose-module.nix;
-        config._module.args.pkgs = lib.mkForce pkgs;
-        config._module.args.uid = uid;
-      };
-
-    in
-      composite.config.build.service;
+  evalService = name: modules: (pkgs.callPackage ./eval-service.nix {} { inherit modules uid; }).config.build.service;
 
 in
 {
   options = {
     build.dockerComposeYaml = lib.mkOption {
       type = lib.types.package;
+      description = "";
     };
     build.dockerComposeYamlText = lib.mkOption {
       type = lib.types.string;
+      description = "";
     };
     docker-compose.raw = lib.mkOption {
       type = lib.types.attrs;
+      description = "";
     };
     docker-compose.services = lib.mkOption {
       default = {};
       type = with lib.types; attrsOf (coercedTo unspecified (a: [a]) (listOf unspecified));
+      description = "";
     };
   };
   config = {

src/nix/eval-service.nix

@@ -0,0 +1,24 @@
+{ lib, pkgs, ... }:
+
+{ modules, uid }:
+let
+  composite = lib.evalModules {
+    check = true;
+    modules = builtinModules ++ modules;
+  };
+
+  builtinModules = [
+    argsModule
+    ./service.nix
+    ./service-host-store.nix
+  ];
+
+  argsModule = {
+    _file = ./docker-compose-module.nix;
+    key = ./docker-compose-module.nix;
+    config._module.args.pkgs = lib.mkForce pkgs;
+    config._module.args.uid = uid;
+  };
+
+in
+  composite

src/nix/service.nix

@@ -15,37 +15,46 @@ in
     service.volumes = mkOption {
       type = listOf types.unspecified;
       default = [];
+      description = "";
     };
     service.build.context = mkOption {
       type = nullOr string;
       default = null;
+      description = "";
     };
     service.environment = mkOption {
       type = attrsOf (either string int);
       default = {};
+      description = "";
     };
     service.image = mkOption {
       type = string;
+      description = "";
     };
     service.command = mkOption {
       type = nullOr types.unspecified;
       default = null;
+      description = "";
     };
     service.depends_on = mkOption {
       type = listOf string;
       default = [];
+      description = "";
     };
     service.working_dir = mkOption {
       type = nullOr string;
       default = null;
+      description = "";
     };
     service.entrypoint = mkOption {
       type = nullOr string;
       default = null;
+      description = "";
     };
     service.restart = mkOption {
       type = nullOr string;
       default = null;
+      description = "";
     };
     service.ports = mkOption {
       type = listOf types.unspecified;
@@ -58,10 +67,12 @@ in
     service.expose = mkOption {
       type = listOf string;
       default = [];
+      description = "";
     };
 
     build.service = mkOption {
       type = attrsOf types.unspecified;
+      description = "";
     };
   };
 

tests/default.nix

@@ -5,4 +5,5 @@ in
 
 recurseIntoAttrs {
   test = nixosTest ./arion-test;
+  preEval = pkgs.callPackage ./arion-test/preeval.nix {};
 }