docs: build/install and misc (#8)

docs/about_docs.rst

@@ -6,7 +6,7 @@ The Envoy documentation is composed of a few major sections:
 * :ref:`Introduction <intro>`: This section covers a general overview of what Envoy is, an
   architecture overview, how it is typically deployed, etc.
 
-* :ref:`Installation <install>`: How to build/install Envoy and quickly test it out using Docker.
+* :ref:`Installation <install>`: How to build/install Envoy using Docker.
 
 * :ref:`Configuration <config>`: Detailed configuration instructions. Where relevant, the
   configuration guide also contains information on statistics, runtime configuration, and REST

docs/conf.py

@@ -29,7 +29,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.httpdomain']
+extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.extlinks']
+
+extlinks = {'repo': ('https://github.com/lyft/envoy/blob/master/%s', '')}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/install/building.rst

@@ -0,0 +1,27 @@
+Building
+========
+
+The Envoy build system uses cmake. In order to ease initial building and for a quick start, we
+provide an Ubuntu 14 based docker container that has everything needed inside of it to build
+and *statically link* envoy. The following command will build and run all of the tests.
+
+.. code-block:: console
+
+  docker run -t -i -v <SOURCE_DIR>:/source lyft/envoy-build:latest /bin/bash -c "cd /source && ci/do_ci.sh normal"
+
+In order to build manually, cmake is used like so:
+
+.. code-block:: console
+
+  mkdir build
+  cd build
+  cmake ..
+  make
+
+Note that in order for the above raw build to work, cmake variables will need to be configured so
+that the envoy build can find all of the needed third party dependencies (other variables are also
+available to turn on debug builds, address sanitizer, etc.).
+
+* :repo:`CMakeLists.txt`
+* :repo:`common.cmake`
+* :repo:`thirdparty.cmake`

docs/install/install.rst

@@ -3,17 +3,10 @@
 Building and installation
 =========================
 
-Requirements
---------------
+.. toctree::
+  :maxdepth: 2
 
-Building
---------
-
-Installation
-------------
-
-Reference configurations
-------------------------
-
-configgen
-^^^^^^^^^
+  requirements
+  building
+  installation
+  ref_configs

docs/install/installation.rst

@@ -0,0 +1,6 @@
+Installation
+============
+
+Currently we do not provide any pre-compiled binaries or startup scripts. Typically Envoy will be
+used with the :ref:`hot restart wrapper <operations_hot_restarter>` for launching. In the future we
+may provide OS specific deployment packages.

docs/install/ref_configs.rst

@@ -0,0 +1,9 @@
+Reference configurations
+========================
+
+FIXFIX
+
+configgen
+---------
+
+FIXFIX

docs/install/requirements.rst

@@ -0,0 +1,27 @@
+Requirements
+============
+
+Envoy was initially developed and deployed on Ubuntu 14 LTS. It should work on any reasonably
+recent Linux including Ubuntu 16 LTS.
+
+Envoy has the following requirements:
+
+* GCC 4.9+ (for C++11 regex support)
+* `cotire <https://github.com/sakra/cotire>`_ (last tested with 1.7.8)
+* `spdlog <https://github.com/gabime/spdlog>`_ (last tested with 319a62)
+* `http-parser <https://github.com/nodejs/http-parser>`_ (last tested with 2.7.0)
+* `nghttp2 <https://github.com/nghttp2/nghttp2>`_ (last tested with 1.9.2)
+* `libevent <http://libevent.org/>`_ (last tested with 2.0.22)
+* `tclap <http://tclap.sourceforge.net/>`_ (last tested with 1.2.1)
+* `gperftools <https://github.com/gperftools/gperftools>`_ (last tested with 2.5.0)
+* `jansson <https://github.com/akheron/jansson>`_ (last tesed with 2.7)
+* `openssl <https://www.openssl.org/>`_ (last tesed with 1.0.2h)
+* `protobuf <https://github.com/google/protobuf>`_ (last tested with 3.0.0)
+
+In order to compile and run the tests the following is required:
+
+* `googletest <https://github.com/google/googletest>`_
+
+In order to run code coverage the following is required:
+
+* `gcovr <http://gcovr.com/>`_

docs/intro/deployment_types.rst

@@ -8,8 +8,14 @@ types in increasing order of complexity.
 Service to service only
 -----------------------
 
+FIXFIX
+
 Service to service plus front proxy
 -----------------------------------
 
+FIXFIX
+
 Service to service, front proxy, and double proxy
 -------------------------------------------------
+
+FIXFIX

docs/operations/hot_restarter.rst

@@ -1,2 +1,4 @@
+.. _operations_hot_restarter:
+
 Hot restart Python wrapper
 ==========================