Merge pull request #1698 from metalivedev/1684-Cleanup

Fix #1684: Cleanup introduction, working with repos, "use" index.

docs/sources/commandline/command/cp.rst

@@ -2,12 +2,13 @@
 :description: Copy files/folders from the containers filesystem to the host path
 :keywords: cp, docker, container, documentation, copy
 
-===========================================================
+============================================================================
 ``cp`` -- Copy files/folders from the containers filesystem to the host path
-===========================================================
+============================================================================
 
 ::
 
     Usage: docker cp CONTAINER:RESOURCE HOSTPATH
 
-    Copy files/folders from the containers filesystem to the host path.  Paths are relative to the root of the filesystem.
+    Copy files/folders from the containers filesystem to the host
+    path.  Paths are relative to the root of the filesystem.

docs/sources/concepts/index.rst

@@ -1,16 +0,0 @@
-:title: Overview
-:description: Docker documentation summary
-:keywords: concepts, documentation, docker, containers
-
-
-
-Overview
-========
-
-Contents:
-
-.. toctree::
-   :maxdepth: 1
-
-   ../index
-   manifesto

docs/sources/concepts/manifesto.rst

@@ -1,129 +0,0 @@
-:title: Manifesto
-:description: An overview of Docker and standard containers
-:keywords: containers, lxc, concepts, explanation
-
-.. _dockermanifesto:
-
-Docker Manifesto
-----------------
-
-Docker complements LXC with a high-level API which operates at the
-process level. It runs unix processes with strong guarantees of
-isolation and repeatability across servers.
-
-Docker is a great building block for automating distributed systems:
-large-scale web deployments, database clusters, continuous deployment
-systems, private PaaS, service-oriented architectures, etc.
-
-- **Heterogeneous payloads** Any combination of binaries, libraries,
-  configuration files, scripts, virtualenvs, jars, gems, tarballs, you
-  name it. No more juggling between domain-specific tools. Docker can
-  deploy and run them all.
-- **Any server** Docker can run on any x64 machine with a modern linux
-  kernel - whether it's a laptop, a bare metal server or a VM. This
-  makes it perfect for multi-cloud deployments.
-- **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:: images/lego_docker.jpg
-   :target: http://bricks.argz.com/ins/7823-1/12
-
-What is a Standard Container?
-.............................
-
-Docker defines a unit of software delivery called a Standard
-Container. The goal of a Standard Container is to encapsulate a
-software component and all its dependencies in a format that is
-self-describing and portable, so that any compliant runtime can run it
-without extra dependency, regardless of the underlying machine and the
-contents of the container.
-
-The spec for Standard Containers is currently work in progress, but it
-is very straightforward. It mostly defines 1) an image format, 2) a
-set of standard operations, and 3) an execution environment.
-
-A great analogy for this is the shipping container. Just like Standard
-Containers are a fundamental unit of software delivery, shipping
-containers are a fundamental unit of physical delivery.
-
-Standard operations
-~~~~~~~~~~~~~~~~~~~
-
-Just like shipping containers, Standard Containers define a set of
-STANDARD OPERATIONS. Shipping containers can be lifted, stacked,
-locked, loaded, unloaded and labelled. Similarly, standard containers
-can be started, stopped, copied, snapshotted, downloaded, uploaded and
-tagged.
-
-
-Content-agnostic
-~~~~~~~~~~~~~~~~~~~
-
-Just like shipping containers, Standard Containers are
-CONTENT-AGNOSTIC: all standard operations have the same effect
-regardless of the contents. A shipping container will be stacked in
-exactly the same way whether it contains Vietnamese powder coffee or
-spare Maserati parts. Similarly, Standard Containers are started or
-uploaded in the same way whether they contain a postgres database, a
-php application with its dependencies and application server, or Java
-build artifacts.
-
-Infrastructure-agnostic
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be
-transported to thousands of facilities around the world, and
-manipulated by a wide variety of equipment. A shipping container can
-be packed in a factory in Ukraine, transported by truck to the nearest
-routing center, stacked onto a train, loaded into a German boat by an
-Australian-built crane, stored in a warehouse at a US facility,
-etc. Similarly, a standard container can be bundled on my laptop,
-uploaded to S3, downloaded, run and snapshotted by a build server at
-Equinix in Virginia, uploaded to 10 staging servers in a home-made
-Openstack cluster, then sent to 30 production instances across 3 EC2
-regions.
-
-
-Designed for automation
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Because they offer the same standard operations regardless of content
-and infrastructure, Standard Containers, just like their physical
-counterpart, are extremely well-suited for automation. In fact, you
-could say automation is their secret weapon.
-
-Many things that once required time-consuming and error-prone human
-effort can now be programmed. Before shipping containers, a bag of
-powder coffee was hauled, dragged, dropped, rolled and stacked by 10
-different people in 10 different locations by the time it reached its
-destination. 1 out of 50 disappeared. 1 out of 20 was damaged. The
-process was slow, inefficient and cost a fortune - and was entirely
-different depending on the facility and the type of goods.
-
-Similarly, before Standard Containers, by the time a software
-component ran in production, it had been individually built,
-configured, bundled, documented, patched, vendored, templated, tweaked
-and instrumented by 10 different people on 10 different
-computers. Builds failed, libraries conflicted, mirrors crashed,
-post-it notes were lost, logs were misplaced, cluster updates were
-half-broken. The process was slow, inefficient and cost a fortune -
-and was entirely different depending on the language and
-infrastructure provider.
-
-Industrial-grade delivery
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are 17 million shipping containers in existence, packed with
-every physical good imaginable. Every single one of them can be loaded
-on the same boats, by the same cranes, in the same facilities, and
-sent anywhere in the World with incredible efficiency. It is
-embarrassing to think that a 30 ton shipment of coffee can safely
-travel half-way across the World in *less time* than it takes a
-software team to deliver its code from one datacenter to another
-sitting 10 miles away.
-
-With Standard Containers we can put an end to that embarrassment, by
-making INDUSTRIAL-GRADE DELIVERY of software a reality.

docs/sources/examples/mongodb.rst

@@ -25,7 +25,7 @@ Create an empty file called ``Dockerfile``:
 
 Next, define the parent image you want to use to build your own image on top of.
 Here, we’ll use `Ubuntu <https://index.docker.io/_/ubuntu/>`_ (tag: ``latest``)
-available on the `docker index`_:
+available on the `docker index <http://index.docker.io>`_:
 
 .. code-block:: bash
 

docs/sources/index.rst

@@ -1,11 +1,11 @@
-:title: Welcome to the Docker Documentation
+:title: Docker Documentation
 :description: An overview of the Docker Documentation
 :keywords: containers, lxc, concepts, explanation
 
-Welcome
-=======
+.. image:: static_files/dockerlogo-h.png
 
-.. image:: concepts/images/dockerlogo-h.png
+Introduction
+------------
 
 ``docker``, the Linux Container Runtime, runs Unix processes with
 strong guarantees of isolation across servers. Your software runs

docs/sources/installation/ubuntulinux.rst

@@ -2,10 +2,10 @@
 :description: Please note this project is currently under heavy development. It should not be used in production.
 :keywords: Docker, Docker documentation, requirements, virtualbox, vagrant, git, ssh, putty, cygwin, linux
 
-.. _ubuntu_linux:
-
 **These instructions have changed for 0.6. If you are upgrading from an earlier version, you will need to follow them again.**
 
+.. _ubuntu_linux:
+
 Ubuntu Linux
 ============
 

docs/sources/installation/vagrant.rst

@@ -2,10 +2,10 @@
 :description: This guide will setup a new virtualbox virtual machine with docker installed on your computer.
 :keywords: Docker, Docker documentation, virtualbox, vagrant, git, ssh, putty, cygwin
 
-.. _install_using_vagrant:
-
 **Vagrant installation is temporarily out of date, it will be updated for 0.6 soon.**
 
+.. _install_using_vagrant:
+
 Using Vagrant (Mac, Linux)
 ==========================
 

docs/sources/installation/windows.rst

@@ -2,10 +2,10 @@
 :description: Docker's tutorial to run docker on Windows
 :keywords: Docker, Docker documentation, Windows, requirements, virtualbox, vagrant, git, ssh, putty, cygwin
 
-.. _windows:
-
 **Vagrant installation is temporarily out of date, it will be updated for 0.6 soon.**
 
+.. _windows:
+
 Using Vagrant (Windows)
 =======================
 

docs/sources/toctree.rst

@@ -10,7 +10,7 @@ This documentation has the following resources:
 .. toctree::
    :titlesonly:
 
-   concepts/index
+   Introduction <index>
    installation/index
    use/index
    examples/index
@@ -19,6 +19,3 @@ This documentation has the following resources:
    api/index
    terms/index
    faq
-
-
-

docs/sources/use/builder.rst

@@ -4,13 +4,13 @@
 
 .. _dockerbuilder:
 
-==================
-Dockerfile Builder
-==================
+======================
+Dockerfiles for Images
+======================
 
 **Docker can act as a builder** and read instructions from a text
-Dockerfile to automate the steps you would otherwise make manually to
-create an image. Executing ``docker build`` will run your steps and
+``Dockerfile`` to automate the steps you would otherwise take manually
+to create an image. Executing ``docker build`` will run your steps and
 commit them along the way, giving you a final image.
 
 .. contents:: Table of Contents
@@ -35,6 +35,8 @@ build succeeds:
 Docker will run your steps one-by-one, committing the result if necessary,
 before finally outputting the ID of your new image.
 
+When you're done with your build, you're ready to look into :ref:`image_push`.
+
 2. Format
 =========
 
@@ -48,9 +50,9 @@ The Dockerfile format is quite simple:
 The Instruction is not case-sensitive, however convention is for them to be
 UPPERCASE in order to distinguish them from arguments more easily.
 
-Docker evaluates the instructions in a Dockerfile in order. **The first
-instruction must be `FROM`** in order to specify the base image from
-which you are building.
+Docker evaluates the instructions in a Dockerfile in order. **The
+first instruction must be `FROM`** in order to specify the
+:ref:`base_image_def` from which you are building.
 
 Docker will ignore **comment lines** *beginning* with ``#``. A comment
 marker anywhere in the rest of the line will be treated as an argument.
@@ -68,7 +70,9 @@ building images.
 
 The ``FROM`` instruction sets the :ref:`base_image_def` for subsequent
 instructions. As such, a valid Dockerfile must have ``FROM`` as its
-first instruction.
+first instruction. The image can be any valid image -- it is
+especially easy to start with an image from the
+:ref:`using_public_repositories`
 
 ``FROM`` must be the first non-comment instruction in the
 ``Dockerfile``.
@@ -160,7 +164,7 @@ override the default specified in CMD.
 The ``EXPOSE`` instruction sets ports to be publicly exposed when
 running the image. This is functionally equivalent to running ``docker
 commit -run '{"PortSpecs": ["<port>", "<port2>"]}'`` outside the
-builder.
+builder. Take a look at :ref:`port_redirection` for more information.
 
 3.6 ENV
 -------

docs/sources/use/index.rst

@@ -13,8 +13,8 @@ Contents:
    :maxdepth: 1
 
    basics
+   builder
    workingwithrepository
    port_redirection
-   builder
    puppet
 

docs/sources/use/port_redirection.rst

@@ -3,6 +3,8 @@
 :keywords: Usage, basic port, docker, documentation, examples
 
 
+.. _port_redirection:
+
 Port redirection
 ================
 

docs/sources/use/workingwithrepository.rst

@@ -28,12 +28,18 @@ repositories. You can host your own Registry too! Docker acts as a
 client for these services via ``docker search, pull, login`` and
 ``push``.
 
-Top-level, User, and Your Own Repositories
-------------------------------------------
+.. _using_public_repositories:
+
+Public Repositories
+-------------------
 
 There are two types of public repositories: *top-level* repositories
 which are controlled by the Docker team, and *user* repositories
-created by individual contributors.
+created by individual contributors. Anyone can read from these
+repositories -- they really help people get started quickly! You could
+also use :ref:`using_private_repositories` if you need to keep control
+of who accesses your images, but we will only refer to public
+repositories in these examples.
 
 * Top-level repositories can easily be recognized by **not** having a
   ``/`` (slash) in their name. These repositories can generally be
@@ -46,28 +52,6 @@ created by individual contributors.
 * User images are not checked, it is therefore up to you whether or
   not you trust the creator of this image.
 
-Right now (version 0.5), private repositories are only possible by
-hosting `your own registry
-<https://github.com/dotcloud/docker-registry>`_.  To push or pull to a
-repository on your own registry, you must prefix the tag with the
-address of the registry's host, like this:
-
-.. code-block:: bash
-
-    # Tag to create a repository with the full registry location.
-    # The location (e.g. localhost.localdomain:5000) becomes
-    # a permanent part of the repository name
-    sudo docker tag 0u812deadbeef localhost.localdomain:5000/repo_name
-
-    # Push the new repository to its home location on localhost
-    sudo docker push localhost.localdomain:5000/repo_name
-
-Once a repository has your registry's host name as part of the tag,
-you can push and pull it like any other repository, but it will
-**not** be searchable (or indexed at all) in the Central Index, and
-there will be no user name checking performed. Your registry will
-function completely independently from the Central Index.
-
 Find public images available on the Central Index
 -------------------------------------------------
 
@@ -105,6 +89,7 @@ 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.
 
+.. _container_commit:
 
 Committing a container to a named image
 ---------------------------------------
@@ -117,16 +102,45 @@ your container to an image within your username namespace.
     # for example docker commit $CONTAINER_ID dhrp/kickassapp
     sudo docker commit <container_id> <username>/<repo_name>
 
+.. _image_push:
 
-Pushing a container to its repository
--------------------------------------
+Pushing an image to its repository
+----------------------------------
 
 In order to push an image to its repository you need to have committed
 your container to a named image (see above)
 
-Now you can commit this image to the repository
+Now you can commit this image to the repository designated by its name
+or tag.
 
 .. code-block:: bash
 
     # for example docker push dhrp/kickassapp
     sudo docker push <username>/<repo_name>
+
+.. _using_private_repositories:
+
+Private Repositories
+--------------------
+
+Right now (version 0.5), private repositories are only possible by
+hosting `your own registry
+<https://github.com/dotcloud/docker-registry>`_.  To push or pull to a
+repository on your own registry, you must prefix the tag with the
+address of the registry's host, like this:
+
+.. code-block:: bash
+
+    # Tag to create a repository with the full registry location.
+    # The location (e.g. localhost.localdomain:5000) becomes
+    # a permanent part of the repository name
+    sudo docker tag 0u812deadbeef localhost.localdomain:5000/repo_name
+
+    # Push the new repository to its home location on localhost
+    sudo docker push localhost.localdomain:5000/repo_name
+
+Once a repository has your registry's host name as part of the tag,
+you can push and pull it like any other repository, but it will
+**not** be searchable (or indexed at all) in the Central Index, and
+there will be no user name checking performed. Your registry will
+function completely independently from the Central Index.

docs/theme/docker/layout.html

@@ -212,7 +212,9 @@
         }
 
         // attached handler on click
-        $('.sidebar > ul > li > a').not(':last').click(function(){
+        // Do not attach to first element or last (intro, faq) so that
+        // first and last link directly instead of accordian
+        $('.sidebar > ul > li > a').not(':last').not(':first').click(function(){
 
             var index = $.inArray(this.href, openmenus)