From 0f7f7f20369183b937976094526d249725de782f Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 13 Feb 2019 17:03:03 +0700 Subject: [PATCH] WIP doc --- doc/manual/Makefile | 33 +++++ doc/manual/default.nix | 52 +++++-- doc/manual/introduction.asciidoc | 34 +++++ doc/manual/manual.xml | 52 +++++++ doc/manual/options-to-docbook.xsl | 224 ++++++++++++++++++++++++++++++ doc/manual/preview.html | 87 ++++++++++++ doc/manual/style.css | 159 +++++++++++++++++++++ 7 files changed, 633 insertions(+), 8 deletions(-) create mode 100644 doc/manual/Makefile create mode 100644 doc/manual/introduction.asciidoc create mode 100644 doc/manual/manual.xml create mode 100644 doc/manual/options-to-docbook.xsl create mode 100644 doc/manual/preview.html create mode 100644 doc/manual/style.css diff --git a/doc/manual/Makefile b/doc/manual/Makefile new file mode 100644 index 0000000..c7e0286 --- /dev/null +++ b/doc/manual/Makefile @@ -0,0 +1,33 @@ +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 + $(xsltproc) --xinclude --stringparam profile.condition manual \ + $(docbookxsl)/profiling/profile.xsl manual.xml | \ + $(xsltproc) --output manual.html $(docbookxsl)/xhtml/docbook.xsl - + +# -e 's___' -e 's___' +%.xml: %.asciidoc + asciidoc -b docbook -d book -a nolang $< + sed -e 's///' -i $@ + cat $@ + +install: all + mkdir -p $(docdir) + cp manual.html style.css $(docdir) diff --git a/doc/manual/default.nix b/doc/manual/default.nix index 7352a62..d9f62ef 100644 --- a/doc/manual/default.nix +++ b/doc/manual/default.nix @@ -1,9 +1,8 @@ -{ pkgs ? import ../../nix {} }: +{ pkgs ? import ../../nix {}, version ? "unreleased" }: let - inherit (pkgs) recurseIntoAttrs callPackage runCommand lib; + inherit (pkgs) recurseIntoAttrs callPackage runCommand lib stdenv ; nixosManualPath = s: "${pkgs.path}/nixos/doc/manual/${s}"; - revision = "0.0-fixme"; # FIXME # NixOS module system options in JSON format. options = { moduleType, description, optionsList }: recurseIntoAttrs rec { @@ -19,8 +18,9 @@ let exit 1 fi ${pkgs.buildPackages.libxslt.bin}/bin/xsltproc \ - --stringparam revision '${revision}' \ - -o intermediate.xml ${nixosManualPath "options-to-docbook.xsl"} $optionsXML + --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 ''; @@ -43,6 +43,10 @@ let }; + fixPaths = opt: opt // builtins.trace opt.declarations { + declarations = map (d: lib.strings.removePrefix "/" (lib.strings.removePrefix (toString ../..) (toString d))) opt.declarations; + }; + in recurseIntoAttrs rec { @@ -50,17 +54,49 @@ recurseIntoAttrs rec { moduleType = "composition"; description = "List of Arion composition-level options in JSON format"; optionsList = let composition = import ../../src/nix/eval-composition.nix { inherit pkgs; }; - in lib.optionAttrSetToDocList composition.options; + 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 composition = pkgs.callPackage ../../src/nix/eval-service.nix {} { modules = []; uid = -1; }; - in lib.optionAttrSetToDocList composition.options; + 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 = ./.; + name = "arion-manual"; + version = version; + buildInputs = [ + (pkgs.libxslt.bin or pkgs.libxslt) + pkgs.asciidoc + ]; + XML_CATALOG_FILES = "${pkgs.docbook_xsl}/xml/xsl/docbook/catalog.xml"; + 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 'Configuration Options' 'Service Options' \ + --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 'Configuration Options' 'Composition Options' \ + --replace 'xml:id="configuration-variable-list"' 'xml:id="composition-variable-list"' \ + ; + ls -R + set +x + ''; + }; } diff --git a/doc/manual/introduction.asciidoc b/doc/manual/introduction.asciidoc new file mode 100644 index 0000000..5b5a6ed --- /dev/null +++ b/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. diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml new file mode 100644 index 0000000..fb37b2b --- /dev/null +++ b/doc/manual/manual.xml @@ -0,0 +1,52 @@ + + + + + Arion Manual + Version @version@ + + + + Hercules Labs + + Author + + + + + + + + Installation +
+ Traditional Linux or Mac + + TODO: describe: install Nix and nix-env -i + +
+
+ Not installing: use it in a project + + TODO: describe: using nix-shell or in a script, building + images as part of nix-build, pinning, + see also todomvc-nix. + +
+
+ NixOS + + TODO: describe: Docker + environment.systemPackages + +
+ + + + Getting Started + + + + + + diff --git a/doc/manual/options-to-docbook.xsl b/doc/manual/options-to-docbook.xsl new file mode 100644 index 0000000..d6e28c1 --- /dev/null +++ b/doc/manual/options-to-docbook.xsl @@ -0,0 +1,224 @@ + + + + + + + + + + + + + + Configuration Options + + + + + + + + + + + + + + + + + + + + Type: + + + + + (read only) + + + + + + + Default: + + + + + + + + Example: + + + + + + + + + + + + + + + Related packages: + + + + + + + + Declared by: + + + + + + + Defined by: + + + + + + + + + + + + + + + + + + + +'' +'' + + + + + + + + + + null + + + + + + + '''' + + + "" + + + + + + + + + + + + true + + + + + false + + + + + [ + + + + + ] + + + + + + + + + + { + + + = + ; + + } + + + + + (build of ) + + + + + + + + + + / + + + file:// + + + + + + </> + + + + + + + + + + + + + λ + + + + diff --git a/doc/manual/preview.html b/doc/manual/preview.html new file mode 100644 index 0000000..d505df8 --- /dev/null +++ b/doc/manual/preview.html @@ -0,0 +1,87 @@ + +Arion Manual

Arion Manual

Version unreleased

Hercules Labs

Table of Contents

Introduction
Installation
Traditional Linux or Mac
Not installing: use it in a project
NixOS
Getting Started
Composition Options
Service Options

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 Docker +Compose, which implements the container orchestration functionality.

Instead of configuring the compositions in YAML files like +docker-compose.yaml, Arion uses the 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. +
  • +Use one language and refactor across deployments, configuration and + packaging. +

Installation

Traditional Linux or Mac

+ TODO: describe: install Nix and nix-env -i +

Not installing: use it in a project

+ TODO: describe: using nix-shell or in a script, building + images as part of nix-build, pinning, + see also todomvc-nix. +

NixOS

+ TODO: describe: Docker + environment.systemPackages +

Getting Started

Composition Options

build.dockerComposeYaml

Type: package

Declared by:

src/nix/docker-compose-module.nix
build.dockerComposeYamlText

Type: Concatenated string

Declared by:

src/nix/docker-compose-module.nix
docker-compose.raw

Type: attribute set

Declared by:

src/nix/docker-compose-module.nix
docker-compose.services

Type: attribute set of list of unspecifieds or unspecified convertible to its

Default: + + { + + } + +

Declared by:

src/nix/docker-compose-module.nix

Service Options

build.service

Type: attribute set of unspecifieds

Declared by:

src/nix/service.nix
service.build.context

Type: null or Concatenated string

Default: + null +

Declared by:

src/nix/service.nix
service.command

Type: null or unspecified

Default: + null +

Declared by:

src/nix/service.nix
service.depends_on

Type: list of Concatenated strings

Default: + + [ + + ] + +

Declared by:

src/nix/service.nix
service.entrypoint

Type: null or Concatenated string

Default: + null +

Declared by:

src/nix/service.nix
service.environment

Type: attribute set of Concatenated string or signed integers

Default: + + { + + } + +

Declared by:

src/nix/service.nix
service.expose

Type: list of Concatenated strings

Default: + + [ + + ] + +

Declared by:

src/nix/service.nix
service.image

Type: Concatenated string

Declared by:

src/nix/service.nix
service.ports

Expose ports on host. "host:container" or structured. +See https://docs.docker.com/compose/compose-file/#ports +

Type: list of unspecifieds

Default: + + [ + + ] + +

Declared by:

src/nix/service.nix
service.restart

Type: null or Concatenated string

Default: + null +

Declared by:

src/nix/service.nix
service.useHostStore

Bind mounts the host store if enabled, avoiding copying.

Type: boolean

Default: + false +

Declared by:

src/nix/service-host-store.nix
service.volumes

Type: list of unspecifieds

Default: + + [ + + ] + +

Declared by:

src/nix/service.nix
service.working_dir

Type: null or Concatenated string

Default: + null +

Declared by:

src/nix/service.nix
\ No newline at end of file diff --git a/doc/manual/style.css b/doc/manual/style.css new file mode 100644 index 0000000..9b6e154 --- /dev/null +++ b/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; +}