ref(docs): rewrite with mkdocs

[bacongobbler]

The docs is written in reStructuredText using Sphinx, which is a tool to easily make beautiful
documentation. This has been a great tool for writing our documentation as it included features
like auto-docs for our controller API - which is written in Python - as well as custom themes on
ReadTheDocs. Most of the early contributors were comfortable with ReST when working on Deis v1.
Most of the code was written in Python, so Sphinx was the best choice at the time. Enter 2015, and
Deis v2 is now mostly written in Go. Save for Godeps/, Deis's language distribution per-file is 45%
Python, 40% Go, and 15% other (documentation, bash scripts, YAML/JSON/TOML, Makefiles, Dockerfiles,
etc). This does not include projects like helm/helm and deis/pkg. In short, our usage of Go is
ever-growing and we are drawing a newer crowd to the project. This crowd is comfortable
contributing to Sphinx, but newer contributors are more comfortable writing documentation in more
modern markup languages like Markdown.

We have experimented with using MkDocs with our newer projects like Helm and have seen success in
both readability and contribution efforts, so now is a good opportunity to re-write the Deis
documentation in Markdown while half of it needs to be re-written in preparation for v2. The
auto-docs is a handy feature, but only the core contributors have been taking advantage of the
feature so it won't be missed all that much in favor of greater contributor adoption and ease of
use by tools like MkDocs.

NOTE: some documentation is completely missing pending how we are moving forward on those sections for v2. This is mostly to do with the "Managing Deis" side of things, since logging, monitoring, etc. are potentially all stale for v2.

To test this:

$ pip install -r docs/requirements.txt
$ mkdocs serve

TODO:

• add back Makefile targets
• undo kubernetes-specific changes in some docs to make this strictly a ReST -> Markdown conversion

[bacongobbler]

I went over all this with a fine-combed brush so it should be good to go for reviews now :)

[mboersma]

This is awesome--I tested it and browsed the docs locally. I think MkDocs and Markdown are much more accessible to people in general. I'm good with this change once we restore a make docs target, or at least write down the essential incantation somewhere:

$ pip install -r docs/requirements.txt
$ mkdocs serve

[bacongobbler]

Done. Now the commands to build/test the docs are make deps test or make deps build.

[arschles]

really like the pure markdown, and it was pretty easy to set up the dev env. probably nothing to care about but worth mentioning, I get the following error running mkdocs 0.14.0, python 2.7.10:

/Library/Python/2.7/site-packages/mkdocs/cli.py:86: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options
/Library/Python/2.7/site-packages/mkdocs/cli.py:100: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options
/Library/Python/2.7/site-packages/mkdocs/cli.py:125: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options
/Library/Python/2.7/site-packages/mkdocs/cli.py:145: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options
/Library/Python/2.7/site-packages/mkdocs/cli.py:176: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options
/Library/Python/2.7/site-packages/mkdocs/cli.py:194: Warning: Click detected the use of the unicode_literals __future__ import.  This is heavily discouraged because it can introduce subtle bugs in your code.  You should instead use explicit u"" literals for your unicode strings.  For more information see http://click.pocoo.org/python3/
  @common_options

Anyway, things look good in-browser. LGTM

[bacongobbler]

Yeah that's a mkdocs issue that will be resolved in 0.15. It's out of their hands. Upstream issue