add links to the Dockerfiles as canonical external requirements, add example of building and exposing the docs and simplify the Dockerfile for cacheability

docs/Dockerfile

@@ -1,11 +1,16 @@
 from ubuntu:12.04
 maintainer Nick Stinemates
+#
+#    docker build -t docker:docs . && docker run -p 8000:8000 docker:docs
+#
 
 run apt-get update
 run apt-get install -y python-setuptools make
 run easy_install pip
+#from docs/requirements.txt, but here to increase cacheability
+run pip install Sphinx==1.1.3
+run pip install sphinxcontrib-httpdomain==1.1.8
 add . /docs
-run pip install -r /docs/requirements.txt
 run cd /docs; make docs
 
 expose 8000

docs/README.md

@@ -57,6 +57,9 @@ docs inside the container, even starting a simple HTTP server on port
 build .`` and run the resulting image. This is the equivalent to
 ``make clean server`` since each container starts clean.
 
+In the ``docs/`` directory, run:
+    ```docker build -t docker:docs . && docker run -p 8000:8000 docker:docs```
+
 Usage
 -----
 * Follow the contribution guidelines (``../CONTRIBUTING.md``)

docs/sources/contributing/contributing.rst

@@ -5,5 +5,18 @@
 Contributing to Docker
 ======================
 
-Want to hack on Docker? Awesome! The repository includes `all the instructions you need to get started <https://github.com/dotcloud/docker/blob/master/CONTRIBUTING.md>`_.
+Want to hack on Docker? Awesome! 
 
+The repository includes `all the instructions you need to get
+started <https://github.com/dotcloud/docker/blob/master/CONTRIBUTING.md>`_.
+
+The developer environment `Dockerfile <https://github.com/dotcloud/docker/blob/master/Dockerfile>`_
+specifies the tools and versions used to test and build Docker.
+
+If you're making changes to the documentation, see the
+`README.md <https://github.com/dotcloud/docker/blob/master/docs/README.md>`_.
+
+The documentation environment `Dockerfile <https://github.com/dotcloud/docker/blob/master/docs/Dockerfile>`_
+specifies the tools and versions used to build the Documentation.
+
+Further interesting details can be found in the `Packaging hints <https://github.com/dotcloud/docker/blob/master/hack/PACKAGERS.md>`_.