Fix #621: add new use/base images section. Include examples.

docs/sources/use/baseimages.rst

@@ -0,0 +1,43 @@
+:title: Base Image Creation
+:description: How to create base images
+:keywords: Examples, Usage, base image, docker, documentation, examples
+
+.. _base_image_creation:
+
+Base Image Creation
+===================
+
+So you want to create your own :ref:`base_image_def`? Great!
+
+The specific process will depend heavily on the Linux distribution you
+want to package. We have some examples below, and you are encouraged
+to submit pull requests to contribute new ones.
+
+Getting Started
+...............
+
+In general, you'll want to start with a working machine that is
+running the distribution you'd like to package as a base image, though
+that is not required for some tools like Debian's `Debootstrap
+<https://wiki.debian.org/Debootstrap>`_, which you can also use to
+build Ubuntu images.
+
+It can be as simple as this to create an Ubuntu base image::
+
+  $ sudo debootstrap raring raring > /dev/null
+  $ sudo tar -C raring -c . | sudo docker import - raring
+  a29c15f1bf7a
+  $ sudo docker run raring cat /etc/lsb-release                     
+  DISTRIB_ID=Ubuntu
+  DISTRIB_RELEASE=13.04
+  DISTRIB_CODENAME=raring
+  DISTRIB_DESCRIPTION="Ubuntu 13.04"
+
+There are more example scripts for creating base images in the
+Docker Github Repo:
+
+* `BusyBox <https://github.com/dotcloud/docker/blob/master/contrib/mkimage-busybox.sh>`_
+* `CentOS
+  <https://github.com/dotcloud/docker/blob/master/contrib/mkimage-centos.sh>`_
+* `Debian
+  <https://github.com/dotcloud/docker/blob/master/contrib/mkimage-debian.sh>`_

docs/sources/use/builder.rst

@@ -71,8 +71,8 @@ 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. The image can be any valid image -- it is
-especially easy to start with an image from the
+especially easy to start by **pulling an image** from the
-:ref:`using_public_repositories`
+:ref:`using_public_repositories`.
 
 ``FROM`` must be the first non-comment instruction in the
 ``Dockerfile``.

docs/sources/use/index.rst

@@ -15,6 +15,6 @@ Contents:
    basics
    builder
    workingwithrepository
+   baseimages
    port_redirection
    puppet
-