Documentation enhancements

Making metadata:
- more consistent
- more specific (fixed copy pasting)
- refine coverage

Insecure information cleanup

Removing no longer used files:
- mkdocs is gone
- the registry diagram is not used, and is a bit silly :)

Minor fixes

Fixing links

Recipes:
- harmonized code sections style to the rest of the docs
- harmonized recipe "style"
- listing new recipes

Enhance deploying

Signed-off-by: Olivier Gambier <olivier@docker.com>

docs/osx-setup-guide.md

@@ -1,62 +1,79 @@
 <!--[metadata]>
 +++
-draft = "true"
+title = "Running on OSX"
+description = "Explains how to run a registry on OSX"
+keywords = ["registry, on-prem, images, tags, repository, distribution, osx, recipe, advanced"]
 +++
 <![end-metadata]-->
 
 # OS X Setup Guide
 
-This guide will walk you through running the new Go based [Docker registry](https://github.com/docker/distribution) on your local OS X machine.
+## Use-case
+
+This is useful if you intend to run a registry server natively on OSX.
+
+### Alternatives
+
+You can start a VM on OSX, and deploy your registry normally as a container using Docker inside that VM.
+
+The simplest road to get there is traditionally to use the [docker Toolbox](https://www.docker.com/toolbox), or [docker-machine](https://docs.docker.com/machine/), which usually relies on the [boot2docker](http://boot2docker.io/) iso inside a VirtualBox VM.
+
+### Solution
+
+Using the method described here, you install and compile your own from the git repository and run it as an OSX agent.
+
+### Gotchas
+
+Production services operation on OSX is out of scope of this document. Be sure you understand well these aspects before considering going to production with this.
+
+## Setup golang on your machine
+
+If you know, safely skip to the next section.
+
+If you don't, the TLDR is:
+
+    bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
+    source ~/.gvm/scripts/gvm
+    gvm install go1.4.2
+    gvm use go1.4.2
+
+If you want to understand, you should read [How to Write Go Code](https://golang.org/doc/code.html).
 
 ## Checkout the Docker Distribution source tree
 
-```
-mkdir -p $GOPATH/src/github.com/docker
-git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution
-cd $GOPATH/src/github.com/docker/distribution
-```
+    mkdir -p $GOPATH/src/github.com/docker
+    git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution
+    cd $GOPATH/src/github.com/docker/distribution
 
-## Build the registry binary
+## Build the binary
 
-```
-GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
-sudo cp bin/registry /usr/local/libexec/registry
-```
+    GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
+    sudo cp bin/registry /usr/local/libexec/registry
 
 ## Setup
 
 Copy the registry configuration file in place:
 
-```
-mkdir /Users/Shared/Registry
-cp docs/osx/config.yml /Users/Shared/Registry/config.yml
-```
+    mkdir /Users/Shared/Registry
+    cp docs/osx/config.yml /Users/Shared/Registry/config.yml
 
 ## Running the Docker Registry under launchd
 
 Copy the Docker registry plist into place:
 
-```
-plutil -lint docs/osx/com.docker.registry.plist
-cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/
-chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
-```
+    plutil -lint docs/osx/com.docker.registry.plist
+    cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/
+    chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
 
 Start the Docker registry:
 
-```
-launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
-```
+    launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
 
 ### Restarting the docker registry service
 
-```
-launchctl stop com.docker.registry
-launchctl start com.docker.registry
-```
+    launchctl stop com.docker.registry
+    launchctl start com.docker.registry
 
 ### Unloading the docker registry service
 
-```
-launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
-```
+    launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist