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

@@ -13,29 +13,29 @@ 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,63 +52,58 @@ 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

src/docker/checksum.coffee.md

@@ -6,26 +6,26 @@ 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
 

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

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__   
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine.   
+  Name of the docker-machine. __Mandatory__ 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);
 })
 ```
 

src/docker/load.coffee.md

@@ -6,16 +6,16 @@ Load Docker images
 ## 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. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `input` (string)   
-  TAR archive file to read from   
+  TAR archive file to read from.
 * `source` (string)   
-  Alias for the "input" option.   
+  Alias for the "input" option.
 * `checksum` (string)   
-  If provided, will check if attached input archive to checksum already exist.   
-  Not native to docker. But implemented to get better performance.   
+  If provided, will check if attached input archive to checksum already exist.
+  Not native to docker. But implemented to get better performance.
 
 ## Callback parameters
 
@@ -35,14 +35,8 @@ nikita.docker.load({
   image: 'nikita/load_test:latest',
   machine: machine,
   source: source + "/nikita_load.tar"
-}, function(err, loaded, 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 loaded: ' + status);
 })
 ```
 

src/docker/logout.coffee.md

@@ -7,16 +7,16 @@ specified  is the default.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `registry` (string)   
-  Address of the registry server. "https://index.docker.io/v1/" by default   
+  Address of the registry server, default to "https://index.docker.io/v1/".
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `code` (int|array)   
-  Expected code(s) returned by the command, int or array of int, default to 0.   
+  Expected code(s) returned by the command, int or array of int, default to 0.
 * `code_skipped`   
   Expected code(s) returned by the command if it has no effect, executed will
-  not be incremented, int or array of int.   
+  not be incremented, int or array of int.
 
 ## Callback parameters
 
@@ -30,14 +30,8 @@ specified  is the default.
 ```javascript
 nikita.docker.pause({
   container: 'toto'
-}, 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 : 'Logout: ' + status);
 })
 ```