From 7557af19d8cc3fba858b3ab67cef4875b6097c42 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Thu, 9 May 2013 17:05:20 -0700 Subject: [PATCH] Major rearrange of the documentation. --- docs/Makefile | 2 +- docs/sources/api/index.rst | 16 ++++ .../search.rst => api/index_search_api.rst} | 7 +- .../api.rst => api/registry_api.rst} | 23 +++--- docs/sources/builder/index.rst | 14 ---- docs/sources/commandline/cli.rst | 4 +- docs/sources/commandline/index.rst | 29 ++++++- .../commandline/workingwithrepository.rst | 42 ---------- .../images}/lego_docker.jpg | Bin docs/sources/concepts/introduction.rst | 2 +- docs/sources/index.rst | 11 +-- docs/sources/index/index.rst | 15 ---- docs/sources/registry/index.rst | 15 ---- docs/sources/{commandline => use}/basics.rst | 4 +- .../{builder/basics.rst => use/builder.rst} | 0 docs/sources/use/index.rst | 18 +++++ docs/sources/use/workingwithrepository.rst | 75 ++++++++++++++++++ docs/theme/docker/layout.html | 1 + 18 files changed, 167 insertions(+), 111 deletions(-) create mode 100644 docs/sources/api/index.rst rename docs/sources/{index/search.rst => api/index_search_api.rst} (84%) rename docs/sources/{registry/api.rst => api/registry_api.rst} (98%) delete mode 100644 docs/sources/builder/index.rst delete mode 100644 docs/sources/commandline/workingwithrepository.rst rename docs/sources/{static_files => concepts/images}/lego_docker.jpg (100%) delete mode 100644 docs/sources/index/index.rst delete mode 100644 docs/sources/registry/index.rst rename docs/sources/{commandline => use}/basics.rst (97%) rename docs/sources/{builder/basics.rst => use/builder.rst} (100%) create mode 100644 docs/sources/use/index.rst create mode 100644 docs/sources/use/workingwithrepository.rst diff --git a/docs/Makefile b/docs/Makefile index 9298123f7f..47ecd9ca89 100644 --- a/docs/Makefile +++ b/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/docs/sources/api/index.rst b/docs/sources/api/index.rst new file mode 100644 index 0000000000..a890414363 --- /dev/null +++ b/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/docs/sources/index/search.rst b/docs/sources/api/index_search_api.rst similarity index 84% rename from docs/sources/index/search.rst rename to docs/sources/api/index_search_api.rst index 498295fa2b..e2f8edc492 100644 --- a/docs/sources/index/search.rst +++ b/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/docs/sources/registry/api.rst b/docs/sources/api/registry_api.rst similarity index 98% rename from docs/sources/registry/api.rst rename to docs/sources/api/registry_api.rst index ec2591af4c..35e1971213 100644 --- a/docs/sources/registry/api.rst +++ b/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/docs/sources/builder/index.rst b/docs/sources/builder/index.rst deleted file mode 100644 index 170be1a5ab..0000000000 --- a/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/docs/sources/commandline/cli.rst b/docs/sources/commandline/cli.rst index 47ecb79e67..1a341d3e5d 100644 --- a/docs/sources/commandline/cli.rst +++ b/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/docs/sources/commandline/index.rst b/docs/sources/commandline/index.rst index 72290fa7a8..e22ee52056 100644 --- a/docs/sources/commandline/index.rst +++ b/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/docs/sources/commandline/workingwithrepository.rst b/docs/sources/commandline/workingwithrepository.rst deleted file mode 100644 index ae749fdb03..0000000000 --- a/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/docs/sources/static_files/lego_docker.jpg b/docs/sources/concepts/images/lego_docker.jpg similarity index 100% rename from docs/sources/static_files/lego_docker.jpg rename to docs/sources/concepts/images/lego_docker.jpg diff --git a/docs/sources/concepts/introduction.rst b/docs/sources/concepts/introduction.rst index b7e1b04f05..9c953d8582 100644 --- a/docs/sources/concepts/introduction.rst +++ b/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/docs/sources/index.rst b/docs/sources/index.rst index 4c46653808..fc46ca8255 100644 --- a/docs/sources/index.rst +++ b/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/docs/sources/index/index.rst b/docs/sources/index/index.rst deleted file mode 100644 index 7637a4e779..0000000000 --- a/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/docs/sources/registry/index.rst b/docs/sources/registry/index.rst deleted file mode 100644 index d3788f53cc..0000000000 --- a/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/docs/sources/commandline/basics.rst b/docs/sources/use/basics.rst similarity index 97% rename from docs/sources/commandline/basics.rst rename to docs/sources/use/basics.rst index 8dd8ec9de3..ffd2a7b96c 100644 --- a/docs/sources/commandline/basics.rst +++ b/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/docs/sources/builder/basics.rst b/docs/sources/use/builder.rst similarity index 100% rename from docs/sources/builder/basics.rst rename to docs/sources/use/builder.rst diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst new file mode 100644 index 0000000000..d3b3a31b18 --- /dev/null +++ b/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/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst new file mode 100644 index 0000000000..c1ce7f455e --- /dev/null +++ b/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/docs/theme/docker/layout.html b/docs/theme/docker/layout.html index 32955159b0..1189ceb14b 100755 --- a/docs/theme/docker/layout.html +++ b/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