docker: doc cleanup #119

CHANGELOG.md

@@ -3,6 +3,8 @@
 
 ## Trunk
 
+* docker: doc cleanup #119
+* misc: merge support null as first argument
 * rubygem: source support glob expression
 * rubygem: improve test suport and resilience
 * rubygem: new fetch, install and remove actions

src/docker/build.coffee.md

@@ -3,39 +3,41 @@
 
 Build docker repository from Dockerfile, from content or from current working
 directory (exclusive options).
+
 The user can choose whether the build is local or on the remote.
 Options are the same than docker build command with nikita's one.
 Be aware than you can not use ADD with content option because docker build
 from STDIN does not support a context.
+
 By default docker always run the build and overwrite existing repositories.
 Status unmodified if the repository is identical to a previous one
 
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `image` (string)   
-  Name of the image. __Mandatory__   
+  Name of the image, required.
 * `tag` (string)   
-  Tag of the image   
+  Tag of the image.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `file`   
-  Dockerfile path   
+  Path to Dockerfile.
 * `content` (string | [string])   
-  Use this text to build the repository.   
+  Use this text to build the repository.
 * `quiet` (boolean)   
-  Suppress the verbose output generated by the containers. Default to false   
+  Suppress the verbose output generated by the containers. Default to false
 * `rm` (boolean)   
-  Remove intermediate containers after build. Default to true   
+  Remove intermediate containers after build, default to true.
 * `force_rm` (boolean)   
-  Always remove intermediate containers during build. Default to false   
+  Always remove intermediate containers during build, default to false.
 * `no_cache` (boolean)   
-  Do not use cache when building the repository. Default to false   
+  Do not use cache when building the repository, default to false.
 * `build_arg` ("k=v" | [])   
-  Send arguments to the build (Must match an ARG command).   
+  Send arguments to the build (Must match an ARG command).
 * `cwd` (string)   
-  change the working directory for the build.   
+  change the working directory for the build.
 
 ## Callback parameters
 
@@ -52,70 +54,65 @@ Status unmodified if the repository is identical to a previous one
 
 ## Example
 
-1- builds a repository from dockerfile without any resourcess
+### Builds a repository from dockerfile without any resourcess
 
 ```javascript
 nikita.docker.build({
-  image: 'ryba/targe-build'
+  image: 'ryba/targe-build',
   source: '/home/ryba/Dockerfile'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
 ```
 
-2- builds an repository from dockerfile with external resources
+### Builds an repository from dockerfile with external resources
 
 In this case nikita download all the external files into a resources directory in the same location
-than the Dockerfile.
-The Dockerfile content:   "
-                            FROM centos6
-                            ADD resources/package.tar.gz /tmp/
-                            ADD resources/configuration.sh /tmp/
-                          "
+than the Dockerfile. The Dockerfile content:
+
+```dockerfile
+FROM centos7
+ADD resources/package.tar.gz /tmp/
+ADD resources/configuration.sh /tmp/
+```
+
 Build directory tree :
-                          ├── Dockerfile
-                          ├── resources
-                          │   ├── package.tar.gz
-                          │   ├── configuration.sh
+
+```
+├── Dockerfile
+├── resources
+│   ├── package.tar.gz
+│   ├── configuration.sh
+```
 
 ```javascript
 nikita.docker.build({
   ssh: ssh
   tag: 'ryba/target-build'
   source: '/home/ryba/Dockerfile'
   resources: ['http://url.com/package.tar.gz/','/home/configuration.sh']
-}, function(err, is_built, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_built){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
 ```
 
-3- builds an repository from stdin
+### Builds an repository from stdin
 
 ```javascript
 nikita.docker.build({
-  ssh: ssh
+  ssh: ssh,
   tag: 'ryba/target-build'
   content: "FROM ubuntu\nRUN echo 'helloworld'"
-}, function(err, is_built, stdout, stderr){})
-``
+}, function(err, is_built, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
+```
 
 ## Source Code
 
     module.exports = (options, callback) ->
       options.log message: "Entering Docker build", level: 'DEBUG', module: 'nikita/lib/docker/build'
-      # Validate parameters and __Mandatory__ conditions
+      # Validation
       options.docker ?= {}
       options[k] ?= v for k, v of options.docker
       return callback Error 'Required option "image"' unless options.image?

src/docker/checksum.coffee.md

@@ -6,32 +6,32 @@ Return the checksum of repository:tag, if it exists. Function not native to dock
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `cwd` (string)   
-  change the working directory for the build.   
+  change the working directory for the build.
 * `image` (string)   
-  Name of the image, required.   
+  Name of the image, required.
 * `repository` (string)   
-  Alias of image.   
+  Alias of image.
 * `machine` (string)   
-  Name of the docker-machine, required if using docker-machine.   
+  Name of the docker-machine, required if using docker-machine.
 * `tag` (string)   
-  Tag of the image, default to latest.   
+  Tag of the image, default to latest.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
+  Error object if any.
 * `status`   
-  True if command was executed.   
+  True if command was executed.
 * `checksum`   
-  Image cheksum if it exist, false otherwise.   
+  Image cheksum if it exist, false otherwise.
 
 ## Source Code
 
     module.exports = (options, callback) ->
       options.log message: "Entering Docker checksum", level: 'DEBUG', module: 'nikita/lib/docker/checksum'
-      # Validate parameters and __Mandatory__ conditions
+      # Validation
       options.docker ?= {}
       options[k] ?= v for k, v of options.docker
       options.image ?= options.repository

src/docker/compose/index.coffee.md

@@ -9,7 +9,7 @@ Create and start containers according to a docker-compose file
 *   `boot2docker` (boolean)   
     Whether to use boot2docker or not, default to false.   
 *   `machine` (string)   
-    Name of the docker-machine. __Mandatory__ if using docker-machine   
+    Name of the docker-machine, required if using docker-machine   
 *   `content` (string)   
     The content of the docker-compose.yml to write if not exist.   
 *   `eof` (string)   
@@ -24,7 +24,7 @@ Create and start containers according to a docker-compose file
 *   `services` (string|array)
     Specify specific services to create.
 *   `target` (string)   
-    The docker-compose.yml absolute's file's path. Mandatory if no content is 
+    The docker-compose.yml absolute's file's path, required if no content is 
     specified.   
 *   `code` (int|array)   
     Expected code(s) returned by the command, int or array of int, default to 0.   

src/docker/cp.coffee.md

@@ -16,13 +16,13 @@ Note, stream are not yet supported.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `machine` (string)   
-  Name of the docker-machine, required if using docker-machine or boot2docker.   
+  Name of the docker-machine, required if using docker-machine or boot2docker.
 * `source` (string)   
-  The path to upload or the container followed by the path to download.   
+  The path to upload or the container followed by the path to download.
 * `target` (string)   
-  The path to download or the container followed by the path to upload.   
+  The path to download or the container followed by the path to upload.
 
 ## Uploading a file
 
@@ -37,9 +37,11 @@ nikita.docker({
 
 ```javascript
 nikita.docker({
-  source: 'my_container:/path/to/source'
+  source: 'my_container:/path/to/source',
   target: writable_stream or '/path/to/target'
-}, function(err, status){})
+}, function(err, status){
+  console.log( err ? err.message : 'Container copied: ' + status);
+});
 ```
 
 ## Source Code
@@ -92,7 +94,6 @@ nikita.docker({
 
 ## Modules Dependencies
 
-    # file = require('../misc').file
     path = require 'path'
     ssh2fs = require 'ssh2-fs'
     docker = require '../misc/docker'

src/docker/exec.coffee.md

@@ -6,27 +6,27 @@ Run a command in a running container
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `code_skipped` (int | array)   
-  The exit code(s) to skip.   
+  The exit code(s) to skip.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine.   
+  Name of the docker-machine, required using docker-machine.
 * `service` (boolean)   
-  if true, run container as a service, else run as a command, true by default.   
+  if true, run container as a service, else run as a command, true by default.
 * `uid` (name | uid)   
-  Username or uid.   
+  Username or uid.
 * `gid` (name | gid)   
-  Groupname or gid.   
+  Groupname or gid.
 
 
 ## Callback parameters
 
 * `err`   
   Error object if any.   
-* `executed`   
-  if command was executed   
+* `status`   
+  True if command was executed in container.
 * `stdout`   
   Stdout value(s) unless `stdout` option is provided.   
 * `stderr`   
@@ -36,18 +36,12 @@ Run a command in a running container
 
 ```javascript
 nikita.docker({
-  ssh: ssh
-  container: 'myContainer'
+  ssh: ssh,
+  container: 'myContainer',
   cmd: '/bin/bash -c "echo toto"'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Command executed: ' + status);
+});
 ```
 
 ## Source Code

src/docker/kill.coffee.md

@@ -9,35 +9,29 @@ SIGNAL is not sent.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.   
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine.   
+  Name of the docker-machine, required if using docker-machine.
 * `signal` (int|string)   
-  Use a specified signal. SIGKILL by default   
+  Use a specified signal. SIGKILL by default.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was killed.
 
 ## Example
 
 ```javascript
 nikita.docker.kill({
-  container: 'toto'
+  container: 'toto',
   signal: 9
-}, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status){  
+  console.log( err ? err.message : 'Container killed: ' + status);
 })
 ```