Merge pull request #320 from sa2ajj/cli-docs

move each command description into a separate document

docs/sources/commandline/cli.rst

@@ -10,312 +10,44 @@ Command Line Interface
 Docker Usage
 ~~~~~~~~~~~~
 
-::
+To list available commands, either run ``docker`` with no parameters or execute
+``docker help``::
 
   $ docker
     Usage: docker COMMAND [arg...]
 
     A self-sufficient runtime for linux containers.
 
-    Commands:
-        attach    Attach to a running container
-        commit    Create a new image from a container's changes
-        diff      Inspect changes on a container's filesystem
-        export    Stream the contents of a container as a tar archive
-        history   Show the history of an image
-        images    List images
-        import    Create a new filesystem image from the contents of a tarball
-        info      Display system-wide information
-        inspect   Return low-level information on a container
-        kill      Kill a running container
-        login     Register or Login to the docker registry server
-        logs      Fetch the logs of a container
-        port      Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
-        ps        List containers
-        pull      Pull an image or a repository to the docker registry server
-        push      Push an image or a repository to the docker registry server
-        restart   Restart a running container
-        rm        Remove a container
-        rmi       Remove an image
-        run       Run a command in a new container
-        start     Start a stopped container
-        stop      Stop a running container
-        tag       Tag an image into a repository
-        version   Show the docker version information
-        wait      Block until a container stops, then print its exit code
-
-
-attach
-~~~~~~
-
-::
-
-  Usage: docker attach [OPTIONS]
-
-  Attach to a running container
-
-    -e=true: Attach to stderr
-    -i=false: Attach to stdin
-    -o=true: Attach to stdout
-
-
-commit
-~~~~~~
-
-::
-
-  Usage: docker commit [OPTIONS] CONTAINER [DEST]
-
-  Create a new image from a container's changes
-
-  -m="": Commit message
-
-
-diff
-~~~~
-
-::
-
-  Usage: docker diff CONTAINER [OPTIONS]
-
-  Inspect changes on a container's filesystem
-
-
-export
-~~~~~~
-
-::
-
-    Usage: docker export CONTAINER
-
-    Export the contents of a filesystem as a tar archive
-
-
-history
-~~~~~~~
-
-::
-
-    Usage: docker history [OPTIONS] IMAGE
-
-    Show the history of an image
-
-
-images
-~~~~~~
-
-::
-
-  Usage: docker images [OPTIONS] [NAME]
-
-  List images
-
-    -a=false: show all images
-    -q=false: only show numeric IDs
-
-
-import
-~~~~~~
-
-::
-
-    Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]]
-
-    Create a new filesystem image from the contents of a tarball
-
-
-info
-~~~~
-
-::
-
-  Usage: docker info
-
-  Display system-wide information.
-
-
-inspect
-~~~~~~~
-
-::
-
-  Usage: docker inspect [OPTIONS] CONTAINER
-
-  Return low-level information on a container
-
-
-kill
-~~~~
-
-::
-
-  Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
-
-  Kill a running container
-
-
-login
-~~~~~
-
-::
-
-  Usage: docker login
-
-  Register or Login to the docker registry server
-
-
-logs
-~~~~
-
-::
-
-  Usage: docker logs [OPTIONS] CONTAINER
-
-  Fetch the logs of a container
-
-
-port
-~~~~
-
-::
-
-    Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
-
-    Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
-
-
-ps
-~~
-
-::
-
-    Usage: docker ps [OPTIONS]
-
-    List containers
-
-      -a=false: Show all containers. Only running containers are shown by default.
-      -notrunc=false: Don't truncate output
-      -q=false: Only display numeric IDs
-
-
-pull
-~~~~
-
-::
-
-    Usage: docker pull NAME
-
-    Pull an image or a repository from the registry
-
-push
-~~~~
-
-::
-
-    Usage: docker push NAME
-
-    Push an image or a repository to the registry
-
-
-restart
-~~~~~~~
-
-::
-
-  Usage: docker restart [OPTIONS] NAME
-
-  Restart a running container
-
-
-rm
-~~
-
-::
-
-  Usage: docker rm [OPTIONS] CONTAINER
-
-  Remove a container
-
-
-rmi
-~~~
-
-::
-
-  Usage: docker rmi [OPTIONS] IMAGE
-
-  Remove an image
-
-    -a=false: Use IMAGE as a path and remove ALL images in this path
-    -r=false: Use IMAGE as a regular expression instead of an exact name
-
-
-run
-~~~
-
-::
-
-  Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...]
-
-  Run a command in a new container
-
-    -c="": Comment
-    -i=false: Keep stdin open even if not attached
-    -m=0: Memory limit (in bytes)
-    -p=[]: Map a network port to the container
-    -t=false: Allocate a pseudo-tty
-    -h="": Container host name
-    -u="": Username or UID
-
-
-start
-~~~~~
-
-::
-
-  Usage: docker start [OPTIONS] NAME
-
-  Start a stopped container
-
-
-stop
-~~~~
-
-::
-
-  Usage: docker stop [OPTIONS] NAME
-
-  Stop a running container
-
-
-tag
-~~~
-
-::
-
-    Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG]
-
-    Tag an image into a repository
-
-      -f=false: Force
-
-
-version
-~~~~~~~
-
-::
-
-  Usage: docker version
-
-  Show the docker version information
-
-
-wait
-~~~~
-
-::
-
-  Usage: docker wait [OPTIONS] NAME
-
-  Block until a container stops, then print its exit code.
-
+    ...
+
+Available Commands
+~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   command/attach
+   command/commit
+   command/diff
+   command/export
+   command/history
+   command/images
+   command/import
+   command/info
+   command/inspect
+   command/kill
+   command/login
+   command/logs
+   command/port
+   command/ps
+   command/pull
+   command/push
+   command/restart
+   command/rm
+   command/rmi
+   command/run
+   command/start
+   command/stop
+   command/tag
+   command/version
+   command/wait

docs/sources/commandline/command/attach.rst

@@ -0,0 +1,9 @@
+===========================================
+``attach`` -- Attach to a running container
+===========================================
+
+::
+
+    Usage: docker attach CONTAINER
+
+    Attach to a running container

docs/sources/commandline/command/commit.rst

@@ -0,0 +1,11 @@
+===========================================================
+``commit`` -- Create a new image from a container's changes
+===========================================================
+
+::
+
+    Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY [TAG]]
+
+    Create a new image from a container's changes
+
+      -m="": Commit message

docs/sources/commandline/command/diff.rst

@@ -0,0 +1,9 @@
+=======================================================
+``diff`` -- Inspect changes on a container's filesystem
+=======================================================
+
+::
+
+    Usage: docker diff CONTAINER [OPTIONS]
+
+    Inspect changes on a container's filesystem

docs/sources/commandline/command/export.rst

@@ -0,0 +1,9 @@
+=================================================================
+``export`` -- Stream the contents of a container as a tar archive
+=================================================================
+
+::
+
+    Usage: docker export CONTAINER
+
+    Export the contents of a filesystem as a tar archive

docs/sources/commandline/command/history.rst

@@ -0,0 +1,9 @@
+===========================================
+``history`` -- Show the history of an image
+===========================================
+
+::
+
+    Usage: docker history [OPTIONS] IMAGE
+
+    Show the history of an image

docs/sources/commandline/command/images.rst

@@ -0,0 +1,12 @@
+=========================
+``images`` -- List images
+=========================
+
+::
+
+    Usage: docker images [OPTIONS] [NAME]
+
+    List images
+
+      -a=false: show all images
+      -q=false: only show numeric IDs

docs/sources/commandline/command/import.rst

@@ -0,0 +1,9 @@
+==========================================================================
+``import`` -- Create a new filesystem image from the contents of a tarball
+==========================================================================
+
+::
+
+    Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]]
+
+    Create a new filesystem image from the contents of a tarball

docs/sources/commandline/command/info.rst

@@ -0,0 +1,9 @@
+===========================================
+``info`` -- Display system-wide information
+===========================================
+
+::
+
+    Usage: docker info
+
+    Display system-wide information.

docs/sources/commandline/command/inspect.rst

@@ -0,0 +1,9 @@
+==========================================================
+``inspect`` -- Return low-level information on a container
+==========================================================
+
+::
+
+    Usage: docker inspect [OPTIONS] CONTAINER
+
+    Return low-level information on a container

docs/sources/commandline/command/kill.rst

@@ -0,0 +1,9 @@
+====================================
+``kill`` -- Kill a running container
+====================================
+
+::
+
+    Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
+
+    Kill a running container

docs/sources/commandline/command/login.rst

@@ -0,0 +1,9 @@
+============================================================
+``login`` -- Register or Login to the docker registry server
+============================================================
+
+::
+
+    Usage: docker login
+
+    Register or Login to the docker registry server

docs/sources/commandline/command/logs.rst

@@ -0,0 +1,9 @@
+=========================================
+``logs`` -- Fetch the logs of a container
+=========================================
+
+::
+
+    Usage: docker logs [OPTIONS] CONTAINER
+
+    Fetch the logs of a container

docs/sources/commandline/command/port.rst

@@ -0,0 +1,9 @@
+=========================================================================
+``port`` -- Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
+=========================================================================
+
+::
+
+    Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT
+
+    Lookup the public-facing port which is NAT-ed to PRIVATE_PORT

docs/sources/commandline/command/ps.rst

@@ -0,0 +1,13 @@
+=========================
+``ps`` -- List containers
+=========================
+
+::
+
+    Usage: docker ps [OPTIONS]
+
+    List containers
+
+      -a=false: Show all containers. Only running containers are shown by default.
+      -notrunc=false: Don't truncate output
+      -q=false: Only display numeric IDs

docs/sources/commandline/command/pull.rst

@@ -0,0 +1,9 @@
+=========================================================================
+``pull`` -- Pull an image or a repository from the docker registry server
+=========================================================================
+
+::
+
+    Usage: docker pull NAME
+
+    Pull an image or a repository from the registry

docs/sources/commandline/command/push.rst

@@ -0,0 +1,9 @@
+=======================================================================
+``push`` -- Push an image or a repository to the docker registry server
+=======================================================================
+
+::
+
+    Usage: docker push NAME
+
+    Push an image or a repository to the registry

docs/sources/commandline/command/restart.rst

@@ -0,0 +1,9 @@
+==========================================
+``restart`` -- Restart a running container
+==========================================
+
+::
+
+    Usage: docker restart [OPTIONS] NAME
+
+    Restart a running container

docs/sources/commandline/command/rm.rst

@@ -0,0 +1,9 @@
+============================
+``rm`` -- Remove a container
+============================
+
+::
+
+    Usage: docker rm [OPTIONS] CONTAINER
+
+    Remove a container

docs/sources/commandline/command/rmi.rst

@@ -0,0 +1,9 @@
+==========================
+``rmi`` -- Remove an image
+==========================
+
+::
+
+    Usage: docker rmimage [OPTIONS] IMAGE
+
+    Remove an image

docs/sources/commandline/command/run.rst

@@ -0,0 +1,19 @@
+===========================================
+``run`` -- Run a command in a new container
+===========================================
+
+::
+
+    Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...]
+
+    Run a command in a new container
+
+      -a=map[]: Attach to stdin, stdout or stderr.
+      -d=false: Detached mode: leave the container running in the background
+      -e=[]: Set environment variables
+      -h="": Container host name
+      -i=false: Keep stdin open even if not attached
+      -m=0: Memory limit (in bytes)
+      -p=[]: Map a network port to the container
+      -t=false: Allocate a pseudo-tty
+      -u="": Username or UID

docs/sources/commandline/command/start.rst

@@ -0,0 +1,9 @@
+======================================
+``start`` -- Start a stopped container
+======================================
+
+::
+
+    Usage: docker start [OPTIONS] NAME
+
+    Start a stopped container

docs/sources/commandline/command/stop.rst

@@ -0,0 +1,9 @@
+====================================
+``stop`` -- Stop a running container
+====================================
+
+::
+
+    Usage: docker stop [OPTIONS] NAME
+
+    Stop a running container

docs/sources/commandline/command/tag.rst

@@ -0,0 +1,11 @@
+=========================================
+``tag`` -- Tag an image into a repository
+=========================================
+
+::
+
+    Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG]
+
+    Tag an image into a repository
+
+      -f=false: Force

docs/sources/commandline/command/version.rst

@@ -0,0 +1,3 @@
+==================================================
+``version`` -- Show the docker version information
+==================================================

docs/sources/commandline/command/wait.rst

@@ -0,0 +1,9 @@
+===================================================================
+``wait`` -- Block until a container stops, then print its exit code
+===================================================================
+
+::
+
+    Usage: docker wait [OPTIONS] NAME
+
+    Block until a container stops, then print its exit code.