From 0e4b996e2f94793a4f3b8888b436ebda0edbeb84 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Thu, 9 May 2013 17:05:20 -0700 Subject: [PATCH 1/3] Major rearrange of the documentation. Upstream-commit: 7557af19d8cc3fba858b3ab67cef4875b6097c42 Component: engine --- components/engine/docs/Makefile | 2 +- components/engine/docs/sources/api/index.rst | 16 ++++ .../search.rst => api/index_search_api.rst} | 7 +- .../api.rst => api/registry_api.rst} | 23 +++--- .../engine/docs/sources/builder/index.rst | 14 ---- .../engine/docs/sources/commandline/cli.rst | 4 +- .../engine/docs/sources/commandline/index.rst | 29 ++++++- .../commandline/workingwithrepository.rst | 42 ---------- .../images}/lego_docker.jpg | Bin .../docs/sources/concepts/introduction.rst | 2 +- components/engine/docs/sources/index.rst | 11 +-- .../engine/docs/sources/index/index.rst | 15 ---- .../engine/docs/sources/registry/index.rst | 15 ---- .../sources/{commandline => use}/basics.rst | 4 +- .../{builder/basics.rst => use/builder.rst} | 0 components/engine/docs/sources/use/index.rst | 18 +++++ .../sources/use/workingwithrepository.rst | 75 ++++++++++++++++++ .../engine/docs/theme/docker/layout.html | 1 + 18 files changed, 167 insertions(+), 111 deletions(-) create mode 100644 components/engine/docs/sources/api/index.rst rename components/engine/docs/sources/{index/search.rst => api/index_search_api.rst} (87%) rename components/engine/docs/sources/{registry/api.rst => api/registry_api.rst} (98%) delete mode 100644 components/engine/docs/sources/builder/index.rst delete mode 100644 components/engine/docs/sources/commandline/workingwithrepository.rst rename components/engine/docs/sources/{static_files => concepts/images}/lego_docker.jpg (100%) delete mode 100644 components/engine/docs/sources/index/index.rst delete mode 100644 components/engine/docs/sources/registry/index.rst rename components/engine/docs/sources/{commandline => use}/basics.rst (97%) rename components/engine/docs/sources/{builder/basics.rst => use/builder.rst} (100%) create mode 100644 components/engine/docs/sources/use/index.rst create mode 100644 components/engine/docs/sources/use/workingwithrepository.rst diff --git a/components/engine/docs/Makefile b/components/engine/docs/Makefile index 9298123f7f..47ecd9ca89 100644 --- a/components/engine/docs/Makefile +++ b/components/engine/docs/Makefile @@ -44,7 +44,7 @@ clean: -rm -rf $(BUILDDIR)/* docs: - -rm -rf $(BUILDDIR)/* + #-rm -rf $(BUILDDIR)/* $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The documentation pages are now in $(BUILDDIR)/html." diff --git a/components/engine/docs/sources/api/index.rst b/components/engine/docs/sources/api/index.rst new file mode 100644 index 0000000000..a890414363 --- /dev/null +++ b/components/engine/docs/sources/api/index.rst @@ -0,0 +1,16 @@ +:title: docker documentation +:description: docker documentation +:keywords: + +API's +============= + +This following : + +.. toctree:: + :maxdepth: 3 + + registry_api + index_search_api + + diff --git a/components/engine/docs/sources/index/search.rst b/components/engine/docs/sources/api/index_search_api.rst similarity index 87% rename from components/engine/docs/sources/index/search.rst rename to components/engine/docs/sources/api/index_search_api.rst index 498295fa2b..e2f8edc492 100644 --- a/components/engine/docs/sources/index/search.rst +++ b/components/engine/docs/sources/api/index_search_api.rst @@ -1,3 +1,8 @@ +:title: Docker Index documentation +:description: Documentation for docker Index +:keywords: docker, index, api + + ======================= Docker Index Search API ======================= @@ -32,7 +37,7 @@ Search {"name": "base2", "description": "A base ubuntu64 image..."}, ] } - + :query q: what you want to search for :statuscode 200: no error :statuscode 500: server error \ No newline at end of file diff --git a/components/engine/docs/sources/registry/api.rst b/components/engine/docs/sources/api/registry_api.rst similarity index 98% rename from components/engine/docs/sources/registry/api.rst rename to components/engine/docs/sources/api/registry_api.rst index ec2591af4c..35e1971213 100644 --- a/components/engine/docs/sources/registry/api.rst +++ b/components/engine/docs/sources/api/registry_api.rst @@ -1,3 +1,8 @@ +:title: docker Registry documentation +:description: Documentation for docker Registry and Registry API +:keywords: docker, registry, api, index + + =================== Docker Registry API =================== @@ -44,7 +49,7 @@ We expect that there will be multiple registries out there. To help to grasp the .. note:: - Mirror registries and private registries which do not use the Index don’t even need to run the registry code. They can be implemented by any kind of transport implementing HTTP GET and PUT. Read-only registries can be powered by a simple static HTTP server. + Mirror registries and private registries which do not use the Index don’t even need to run the registry code. They can be implemented by any kind of transport implementing HTTP GET and PUT. Read-only registries can be powered by a simple static HTTP server. .. note:: @@ -107,7 +112,7 @@ API (pulling repository foo/bar): Jsonified checksums (see part 4.4.1) 3. (Docker -> Registry) GET /v1/repositories/foo/bar/tags/latest - **Headers**: + **Headers**: Authorization: Token signature=123abc,repository=”foo/bar”,access=write 4. (Registry -> Index) GET /v1/repositories/foo/bar/images @@ -121,10 +126,10 @@ API (pulling repository foo/bar): **Action**: ( Lookup token see if they have access to pull.) - If good: + If good: HTTP 200 OK Index will invalidate the token - If bad: + If bad: HTTP 401 Unauthorized 5. (Docker -> Registry) GET /v1/images/928374982374/ancestry @@ -186,9 +191,9 @@ API (pushing repos foo/bar): **Headers**: Authorization: Token signature=123abc,repository=”foo/bar”,access=write **Action**:: - - Index: + - Index: will invalidate the token. - - Registry: + - Registry: grants a session (if token is approved) and fetches the images id 5. (Docker -> Registry) PUT /v1/images/98765432_parent/json @@ -223,7 +228,7 @@ API (pushing repos foo/bar): **Body**: (The image, id’s, tags and checksums) - [{“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”, + [{“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”, “checksum”: “b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}] **Return** HTTP 204 @@ -296,7 +301,7 @@ POST /v1/users {"email": "sam@dotcloud.com", "password": "toto42", "username": "foobar"'} **Validation**: - - **username** : min 4 character, max 30 characters, all lowercase no special characters. + - **username** : min 4 character, max 30 characters, all lowercase no special characters. - **password**: min 5 characters **Valid**: return HTTP 200 @@ -387,7 +392,7 @@ PUT /v1/repositories///images **Body**: [ {“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”, “checksum”: “sha256:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”} ] - + **Return** 204 5. Chaining Registries diff --git a/components/engine/docs/sources/builder/index.rst b/components/engine/docs/sources/builder/index.rst deleted file mode 100644 index 170be1a5ab..0000000000 --- a/components/engine/docs/sources/builder/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -:title: docker documentation -:description: Documentation for docker builder -:keywords: docker, builder, dockerfile - - -Builder -======= - -Contents: - -.. toctree:: - :maxdepth: 2 - - basics diff --git a/components/engine/docs/sources/commandline/cli.rst b/components/engine/docs/sources/commandline/cli.rst index 47ecb79e67..1a341d3e5d 100644 --- a/components/engine/docs/sources/commandline/cli.rst +++ b/components/engine/docs/sources/commandline/cli.rst @@ -4,7 +4,7 @@ .. _cli: -Command Line Interface +Overview ====================== Docker Usage @@ -24,7 +24,7 @@ Available Commands ~~~~~~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 command/attach command/build diff --git a/components/engine/docs/sources/commandline/index.rst b/components/engine/docs/sources/commandline/index.rst index 72290fa7a8..e22ee52056 100644 --- a/components/engine/docs/sources/commandline/index.rst +++ b/components/engine/docs/sources/commandline/index.rst @@ -11,6 +11,31 @@ Contents: .. toctree:: :maxdepth: 3 - basics - workingwithrepository cli + command/attach + command/build + 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/search + command/start + command/stop + command/tag + command/version + command/wait \ No newline at end of file diff --git a/components/engine/docs/sources/commandline/workingwithrepository.rst b/components/engine/docs/sources/commandline/workingwithrepository.rst deleted file mode 100644 index ae749fdb03..0000000000 --- a/components/engine/docs/sources/commandline/workingwithrepository.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _working_with_the_repository: - -Working with the repository -============================ - -Connecting to the repository ----------------------------- - -You create a user on the central docker repository by running - -.. code-block:: bash - - docker login - - -If your username does not exist it will prompt you to also enter a password and your e-mail address. It will then -automatically log you in. - - -Committing a container to a named image ---------------------------------------- - -In order to commit to the repository it is required to have committed your container to an image with your namespace. - -.. code-block:: bash - - # for example docker commit $CONTAINER_ID dhrp/kickassapp - docker commit / - - -Pushing a container to the repository ------------------------------------------ - -In order to push an image to the repository you need to have committed your container to a named image (see above) - -Now you can commit this image to the repository - -.. code-block:: bash - - # for example docker push dhrp/kickassapp - docker push - diff --git a/components/engine/docs/sources/static_files/lego_docker.jpg b/components/engine/docs/sources/concepts/images/lego_docker.jpg similarity index 100% rename from components/engine/docs/sources/static_files/lego_docker.jpg rename to components/engine/docs/sources/concepts/images/lego_docker.jpg diff --git a/components/engine/docs/sources/concepts/introduction.rst b/components/engine/docs/sources/concepts/introduction.rst index b7e1b04f05..9c953d8582 100644 --- a/components/engine/docs/sources/concepts/introduction.rst +++ b/components/engine/docs/sources/concepts/introduction.rst @@ -20,7 +20,7 @@ Docker is a great building block for automating distributed systems: large-scale - **Isolation** docker isolates processes from each other and from the underlying host, using lightweight containers. - **Repeatability** Because containers are isolated in their own filesystem, they behave the same regardless of where, when, and alongside what they run. -.. image:: http://www.docker.io/_static/lego_docker.jpg +.. image:: images/lego_docker.jpg What is a Standard Container? diff --git a/components/engine/docs/sources/index.rst b/components/engine/docs/sources/index.rst index 4c46653808..fc46ca8255 100644 --- a/components/engine/docs/sources/index.rst +++ b/components/engine/docs/sources/index.rst @@ -12,14 +12,11 @@ This documentation has the following resources: concepts/index installation/index + use/index examples/index - contributing/index commandline/index - registry/index - index/index - builder/index - remote-api/index + contributing/index + api/index faq - -.. image:: http://www.docker.io/_static/lego_docker.jpg +.. image:: concepts/images/lego_docker.jpg diff --git a/components/engine/docs/sources/index/index.rst b/components/engine/docs/sources/index/index.rst deleted file mode 100644 index 7637a4e779..0000000000 --- a/components/engine/docs/sources/index/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -:title: Docker Index documentation -:description: Documentation for docker Index -:keywords: docker, index, api - - - -Index -===== - -Contents: - -.. toctree:: - :maxdepth: 2 - - search diff --git a/components/engine/docs/sources/registry/index.rst b/components/engine/docs/sources/registry/index.rst deleted file mode 100644 index d3788f53cc..0000000000 --- a/components/engine/docs/sources/registry/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -:title: docker Registry documentation -:description: Documentation for docker Registry and Registry API -:keywords: docker, registry, api, index - - - -Registry -======== - -Contents: - -.. toctree:: - :maxdepth: 2 - - api diff --git a/components/engine/docs/sources/commandline/basics.rst b/components/engine/docs/sources/use/basics.rst similarity index 97% rename from components/engine/docs/sources/commandline/basics.rst rename to components/engine/docs/sources/use/basics.rst index 8dd8ec9de3..ffd2a7b96c 100644 --- a/components/engine/docs/sources/commandline/basics.rst +++ b/components/engine/docs/sources/use/basics.rst @@ -76,8 +76,8 @@ Expose a service on a TCP port echo "Daemon received: $(docker logs $JOB)" -Committing (saving) an image ------------------------------ +Committing (saving) a container state +------------------------------------- Save your containers state to a container image, so the state can be re-used. diff --git a/components/engine/docs/sources/builder/basics.rst b/components/engine/docs/sources/use/builder.rst similarity index 100% rename from components/engine/docs/sources/builder/basics.rst rename to components/engine/docs/sources/use/builder.rst diff --git a/components/engine/docs/sources/use/index.rst b/components/engine/docs/sources/use/index.rst new file mode 100644 index 0000000000..d3b3a31b18 --- /dev/null +++ b/components/engine/docs/sources/use/index.rst @@ -0,0 +1,18 @@ +:title: docker documentation +:description: -- todo: change me +:keywords: todo: change me + + + +Use +======== + +Contents: + +.. toctree:: + :maxdepth: 1 + + basics + workingwithrepository + builder + diff --git a/components/engine/docs/sources/use/workingwithrepository.rst b/components/engine/docs/sources/use/workingwithrepository.rst new file mode 100644 index 0000000000..c1ce7f455e --- /dev/null +++ b/components/engine/docs/sources/use/workingwithrepository.rst @@ -0,0 +1,75 @@ +.. _working_with_the_repository: + +Working with the repository +============================ + + +Top-level repositories and user repositories +-------------------------------------------- + +Generally, there are two types of repositories: Top-level repositories which are controlled by the people behind +Docker, and user repositories. + +* Top-level repositories can easily be recognized by not having a / (slash) in their name. These repositories can + generally be trusted. +* User repositories always come in the form of /. This is what your published images will look like. +* User images are not checked, it is therefore up to you whether or not you trust the creator of this image. + + +Find public images available on the index +----------------------------------------- + +Seach by name, namespace or description + +.. code-block:: bash + + docker search + + +Download them simply by their name + +.. code-block:: bash + + docker pull + + +Very similarly you can search for and browse the index online on https://index.docker.io + + +Connecting to the repository +---------------------------- + +You can create a user on the central docker repository online, or by running + +.. code-block:: bash + + docker login + + +If your username does not exist it will prompt you to also enter a password and your e-mail address. It will then +automatically log you in. + + +Committing a container to a named image +--------------------------------------- + +In order to commit to the repository it is required to have committed your container to an image with your namespace. + +.. code-block:: bash + + # for example docker commit $CONTAINER_ID dhrp/kickassapp + docker commit / + + +Pushing a container to the repository +----------------------------------------- + +In order to push an image to the repository you need to have committed your container to a named image (see above) + +Now you can commit this image to the repository + +.. code-block:: bash + + # for example docker push dhrp/kickassapp + docker push + diff --git a/components/engine/docs/theme/docker/layout.html b/components/engine/docs/theme/docker/layout.html index 32955159b0..1189ceb14b 100755 --- a/components/engine/docs/theme/docker/layout.html +++ b/components/engine/docs/theme/docker/layout.html @@ -206,6 +206,7 @@ } else { //$('.sidebar > ul > li > ul').slideUp(100); var current = $(this); + setTimeout(function() { $('.sidebar > ul > li').removeClass('current'); current.parent().addClass('current'); // toggle before effect From 8767bd1f29da49d7c54462e77806bab2d5539ac3 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Fri, 10 May 2013 12:25:02 -0700 Subject: [PATCH 2/3] Updated commands index to show better title. Small syntax fix in couchDB Upstream-commit: 8946b75a0b8bce77f630020f6c0fcdae3404b922 Component: engine --- .../engine/docs/sources/commandline/index.rst | 54 +++++++++---------- .../sources/examples/couchdb_data_volumes.rst | 2 +- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/components/engine/docs/sources/commandline/index.rst b/components/engine/docs/sources/commandline/index.rst index e22ee52056..179903f80d 100644 --- a/components/engine/docs/sources/commandline/index.rst +++ b/components/engine/docs/sources/commandline/index.rst @@ -12,30 +12,30 @@ Contents: :maxdepth: 3 cli - command/attach - command/build - 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/search - command/start - command/stop - command/tag - command/version - command/wait \ No newline at end of file + attach + build + commit + diff + export + history + images + import + info + inspect + kill + login + logs + port + ps + pull + push + restart + rm + rmi + run + search + start + stop + tag + version + wait \ No newline at end of file diff --git a/components/engine/docs/sources/examples/couchdb_data_volumes.rst b/components/engine/docs/sources/examples/couchdb_data_volumes.rst index df1b5299a4..1b1d7ff79c 100644 --- a/components/engine/docs/sources/examples/couchdb_data_volumes.rst +++ b/components/engine/docs/sources/examples/couchdb_data_volumes.rst @@ -5,7 +5,7 @@ .. _running_couchdb_service: Create a CouchDB service -====================== +======================== .. include:: example_header.inc From 9967e83f8f1be4c2fb084629b3f7eedd026fe9d3 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Mon, 13 May 2013 11:21:28 -0700 Subject: [PATCH 3/3] Moved docker-remote-api doc to api section Upstream-commit: 6390d2501088f74815adff5e1cb0ba5886ed057e Component: engine --- .../api.rst => api/docker_remote_api.rst} | 0 components/engine/docs/sources/api/index.rst | 1 + .../engine/docs/sources/remote-api/index.rst | 15 --------------- 3 files changed, 1 insertion(+), 15 deletions(-) rename components/engine/docs/sources/{remote-api/api.rst => api/docker_remote_api.rst} (100%) delete mode 100644 components/engine/docs/sources/remote-api/index.rst diff --git a/components/engine/docs/sources/remote-api/api.rst b/components/engine/docs/sources/api/docker_remote_api.rst similarity index 100% rename from components/engine/docs/sources/remote-api/api.rst rename to components/engine/docs/sources/api/docker_remote_api.rst diff --git a/components/engine/docs/sources/api/index.rst b/components/engine/docs/sources/api/index.rst index a890414363..8c118bcbc0 100644 --- a/components/engine/docs/sources/api/index.rst +++ b/components/engine/docs/sources/api/index.rst @@ -12,5 +12,6 @@ This following : registry_api index_search_api + docker_remote_api diff --git a/components/engine/docs/sources/remote-api/index.rst b/components/engine/docs/sources/remote-api/index.rst deleted file mode 100644 index 5b3b790b56..0000000000 --- a/components/engine/docs/sources/remote-api/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -:title: docker Remote API documentation -:description: Documentation for docker Remote API -:keywords: docker, rest, api, http - - - -Remote API -========== - -Contents: - -.. toctree:: - :maxdepth: 2 - - api