Add Make recipes for buildout and Sphinx and update docs

Makefile

@@ -234,8 +234,17 @@ check: eslint
 ########################################################################
 ## Documentation
 
+./bin/activate:
+	virtualenv .
+
+.installed.cfg: requirements.txt buildout.cfg
+	./bin/pip install -r requirements.txt
+	./bin/buildout -v
+
+docsdev: ./bin/activate .installed.cfg
+
 .PHONY: html
-html: apidoc
+html: docsdev apidoc
 	rm -rf $(BUILDDIR)/html
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	make apidoc

docs/source/documentation.rst

@@ -30,33 +30,20 @@ under ``docs/source``.
 How to generate HTML from the source files?
 ===========================================
 
-Install Dependencies
---------------------
-
-In order to generate HTML from the source files, you need to have Sphinx and
-the `Sphinx Bootstrap Theme <http://ryan-roemer.github.io/sphinx-bootstrap-theme>`_
-installed.
-
-We use `zc.buildout <http://www.buildout.org/en/latest/>`_ to install Sphinx
-and the theme.
-
-To install Sphinx, do the following inside the Converse repo::
-
-    virtualenv .
-    source bin/activate
-    pip install -r requirements.txt
-    ./bin/buildout
-
 Generate the HTML
 -----------------
 
-After installing the dependencies, you can generate the HTML by simply
-running::
+After installing the dependencies, you can generate the HTML by running::
 
     make html
 
 The HTMl files will be located in ``./docs/html``
 
+What ``make html`` does for you is it installs `zc.buildout <http://www.buildout.org/en/latest/>`_
+which is used to install Sphinx and all its dependencies.
+
+You'll need to have Python and `Virtualenv <https://virtualenv.pypa.io/en/latest/>`_ available on your computer.
+
 .. warning:: When contributing, please don't commit any generated html files.
 
 Serving the documentation