docs: auto generate pouch cli/api docs via code

Signed-off-by: pouchrobot <pouch-dev@list.alibaba-inc.com>
AliyunContainerService · Jun 4, 2019 · 61eb7bb · 61eb7bb
1 parent 68fdb79
commit 61eb7bb
Show file tree

Hide file tree

Showing 3 changed files with 211 additions and 0 deletions.
diff --git a/docs/api/HTTP_API.md b/docs/api/HTTP_API.md
@@ -241,6 +241,156 @@ DELETE /containers/{id}
 * Container
 
 
+<a name="containerarchive"></a>
+### Get an archive of a filesystem resource in a container
+```
+GET /containers/{id}/archive
+```
+
+
+#### Description
+Get a tar archive of a resource in the filesystem of container id.
+
+
+#### Parameters
+
+|Type|Name|Description|Schema|
+|---|---|---|---|
+|**Path**|**id**  <br>*required*|ID or name of the container|string|
+|**Query**|**path**  <br>*required*|Resource in the container’s filesystem to archive.|string|
+
+
+#### Responses
+
+|HTTP Code|Description|Schema|
+|---|---|---|
+|**200**|no error|No Content|
+|**400**|Bad parameter|[0ErrorResponse](#0errorresponse)|
+|**404**|Container or path does not exist|[4ErrorResponse](#4errorresponse)|
+|**500**|server error|[0ErrorResponse](#0errorresponse)|
+
+
+#### Produces
+
+* `application/x-tar`
+
+
+#### Tags
+
+* Copy
+
+
+#### Example HTTP response
+
+##### Response 404
+```
+json :
+{
+  "message" : "No such container: c2ada9df5af8"
+}
+```
+
+
+<a name="putcontainerarchive"></a>
+### Extract an archive of files or folders to a directory in a container
+```
+PUT /containers/{id}/archive
+```
+
+
+#### Description
+Upload a tar archive to be extracted to a path in the filesystem of container id.
+
+
+#### Parameters
+
+|Type|Name|Description|Schema|
+|---|---|---|---|
+|**Path**|**id**  <br>*required*|ID or name of the container|string|
+|**Query**|**copyUIDGID**  <br>*optional*|If “1”, “true”, or “True” then it will copy UID/GID maps to dest file.|string|
+|**Query**|**noOverwriteDirNonDir**  <br>*optional*|If “1”, “true”, or “True” then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa.|string|
+|**Query**|**path**  <br>*required*|Path to a directory in the container to extract the archive’s contents into.|string|
+|**Body**|**inputStream**  <br>*required*|The input stream must be a tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.|string|
+
+
+#### Responses
+
+|HTTP Code|Description|Schema|
+|---|---|---|
+|**200**|The content was extracted successfully|No Content|
+|**400**|Bad parameter|[0ErrorResponse](#0errorresponse)|
+|**403**|Permission denied, the volume or container rootfs is marked as read-only.|[3ErrorResponse](#3errorresponse)|
+|**404**|No such container or path does not exist inside the container|[4ErrorResponse](#4errorresponse)|
+|**500**|Server error|[0ErrorResponse](#0errorresponse)|
+
+
+#### Consumes
+
+* `application/x-tar`
+* `application/octet-stream`
+
+
+#### Tags
+
+* Copy
+
+
+#### Example HTTP response
+
+##### Response 404
+```
+json :
+{
+  "message" : "No such container: c2ada9df5af8"
+}
+```
+
+
+<a name="containerarchiveinfo"></a>
+### Get information about files in a container
+```
+HEAD /containers/{id}/archive
+```
+
+
+#### Description
+A response header `X-Docker-Container-Path-Stat` is return containing a base64 - encoded JSON object with some filesystem header information about the path.
+
+
+#### Parameters
+
+|Type|Name|Description|Schema|
+|---|---|---|---|
+|**Path**|**id**  <br>*required*|ID or name of the container|string|
+|**Query**|**path**  <br>*required*|Resource in the container’s filesystem to archive.|string|
+
+
+#### Responses
+
+|HTTP Code|Description|Schema|
+|---|---|---|
+|**200**|no error  <br>**Headers** :   <br>`X-Docker-Container-Path-Stat` (string) : A base64 - encoded JSON object with some filesystem header information about the path.|No Content|
+|**400**|Bad parameter|[0ErrorResponse](#0errorresponse)|
+|**404**|Container or path does not exist|[4ErrorResponse](#4errorresponse)|
+|**500**|Server error|[0ErrorResponse](#0errorresponse)|
+
+
+#### Tags
+
+* Copy
+
+
+#### Example HTTP response
+
+##### Response 404
+```
+json :
+{
+  "message" : "No such container: c2ada9df5af8"
+}
+```
+
+
 <a name="containerattach"></a>
 ### Attach to a container
 ```
@@ -2335,6 +2485,20 @@ The parameters to filter the log.
 |**Until**  <br>*optional*|Only reture logs before this time, as a UNIX timestamp|string|
 
 
+<a name="containerpathstat"></a>
+### ContainerPathStat
+ContainerPathStat is used to describe the stat of file
+
+
+|Name|Description|Schema|
+|---|---|---|
+|**mode**  <br>*optional*||integer (uint32)|
+|**mtime**  <br>*optional*|modification time.|string (date-time)|
+|**name**  <br>*optional*||string|
+|**path**  <br>*optional*||string|
+|**size**  <br>*optional*||string|
+
+
 <a name="containerprocesslist"></a>
 ### ContainerProcessList
 OK Response to ContainerTop operation

diff --git a/docs/commandline/pouch.md b/docs/commandline/pouch.md
@@ -23,6 +23,7 @@ pouch is a client side tool pouch to interact with daemon side process pouchd. F
 * [pouch build](pouch_build.md)	 - Build an image from a Dockerfile
 * [pouch checkpoint](pouch_checkpoint.md)	 - Manage checkpoint commands
 * [pouch commit](pouch_commit.md)	 - Commit an image from a container
+* [pouch cp](pouch_cp.md)	 - Copy files/folders between a container and the local filesystem
 * [pouch create](pouch_create.md)	 - Create a new container with specified image
 * [pouch events](pouch_events.md)	 - Get real time events from the daemon
 * [pouch exec](pouch_exec.md)	 - Run a command in a running container

diff --git a/docs/commandline/pouch_cp.md b/docs/commandline/pouch_cp.md
@@ -0,0 +1,46 @@
+## pouch cp
+
+Copy files/folders between a container and the local filesystem
+
+### Synopsis
+
+Copy files/folders between a container and the local filesystem
+
+Use '-' as the source to read a tar archive from stdin
+and extract it to a directory destination in a container.
+Use '-' as the destination to stream a tar archive of a
+container source to stdout.
+
+```
+pouch cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-
+  pouch cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH
+```
+
+### Examples
+
+```
+$ pouch cp 8assd1234:/root/foo /home
+$ pouch cp /home/bar 712yasbc:/root
+```
+
+### Options
+
+```
+  -h, --help   help for cp
+```
+
+### Options inherited from parent commands
+
+```
+  -D, --debug              Switch client log level to DEBUG mode
+  -H, --host string        Specify connecting address of Pouch CLI (default "unix:///var/run/pouchd.sock")
+      --tlscacert string   Specify CA file of TLS
+      --tlscert string     Specify cert file of TLS
+      --tlskey string      Specify key file of TLS
+      --tlsverify          Use TLS and verify remote
+```
+
+### SEE ALSO
+
+* [pouch](pouch.md)	 - An efficient container engine
+