docs: add docs for building and examples (#64)

Resolves #39, #32, and #33.

Signed-off-by: Michael Rebello <[email protected]>

README.md

@@ -4,7 +4,7 @@ Mobile client networking libraries based on the [Envoy](https://www.envoyproxy.i
 
 ## Documentation
 
-* TODO(mattklein123): Fill in when hosted.
+- [Official documentation](https://envoy-mobile.github.io/docs/envoy-mobile/latest/index.html)
 
 ## Contact
 
@@ -31,49 +31,3 @@ copyrighted by the *Envoy proxy authors* and the
 [Cloud Native Computing Foundation](https://cncf.io). The Envoy name is used with permission from
 the CNCF under the assumption that if this project finds traction it will be donated to the
 Envoy proxy project.
-
-## Building
-
-### Requirements
-
-- Xcode 10.2.1
-- Bazel 0.26.0
-
-### iOS
-
-#### Build the iOS static framework:
-
-```
-bazel build ios_dist --config=ios
-```
-
-This will yield an `Envoy.framework` in the [`dist` directory](./dist).
-
-#### Run the Swift app:
-
-```
-bazel run //examples/swift/hello_world:app --config=ios
-```
-
-#### Run the Objective-C app:
-
-```
-bazel run //examples/objective-c/hello_world:app --config=ios
-```
-
-### Android
-
-#### Build the Android AAR:
-
-```
-bazel build android_dist --config=android
-```
-
-#### Run the Java app:
-
-```
-bazel mobile-install //examples/java/hello_world:hello_envoy --fat_apk_cpu=x86
-```
-
-If you have issues getting Envoy to compile locally, see the
-[Envoy docs on building with Bazel](https://github.com/envoyproxy/envoy/tree/master/bazel).

docs/README.md

@@ -1,11 +1,20 @@
-# Developer local docs build
+# Envoy Mobile docs
+
+Envoy Mobile's docs are generated using [Sphinx](http://www.sphinx-doc.org),
+and are published
+[here](https://envoy-mobile.github.io/docs/envoy-mobile/latest/index.html).
+
+## Generating docs locally
+
+To generate the docs locally, run:
 
 ```bash
 ./docs/build.sh
 ```
 
-The output can be found in `generated/docs`.
+The output can be then be found in `generated/docs`.
 
-# How the Envoy Mobile website and docs are updated
+## Updating the Envoy Mobile website and docs
 
-TODO(mattklein123): Fill in when publishing is setup.
+The docs website is automatically updated with the latest docs when a commit is
+merged to master. This is done via the [publish script](./publish.sh).

docs/root/start/building/building.rst

@@ -0,0 +1,63 @@
+.. _building:
+
+Building
+========
+
+.. _building_requirements:
+
+In order to compile the artifacts used by the Envoy Mobile library,
+your system must also meet
+`these requirements for building Envoy <https://github.com/envoyproxy/envoy/tree/master/bazel>`_.
+
+--------------------
+Android requirements
+--------------------
+
+- Bazel 0.26.0
+- TODO(junr03): Fill in after https://github.com/lyft/envoy-mobile/pull/60
+
+----------------
+iOS requirements
+----------------
+
+- Bazel 0.26.0
+- Xcode 10.2.1
+- iOS 12.2 / Swift 5.0
+- Note: Requirements are listed in the :repo:`.bazelrc file <.bazelrc>`
+
+.. _android_aar:
+
+-----------
+Android AAR
+-----------
+
+Envoy Mobile can be compiled into an ``.aar`` file for use with Android apps.
+This command is defined in the main :repo:`BUILD <BUILD>` file of the repo, and may be run locally:
+
+``bazel build android_dist --config=android``
+
+Upon completion of the build, you'll see an ``envoy.aar`` file at :repo:`dist/envoy.aar <dist>`.
+
+The ``envoy_mobile_android`` Bazel rule defined in the :repo:`dist BUILD file <dist/BUILD>` provides
+an example of how this artifact may be used.
+
+For a demo of a working app using this artifact, see the :ref:`hello_world` example.
+
+.. _ios_framework:
+
+--------------------
+iOS static framework
+--------------------
+
+Envoy Mobile supports being compiled into a ``.framework`` directory for consumption by iOS apps.
+This command is defined in the main :repo:`BUILD <BUILD>` file of the repo, and may be run locally:
+
+``bazel build ios_dist --config=ios``
+
+Upon completion of the build, you'll see a ``Envoy.framework`` directory at
+:repo:`dist/Envoy.framework <dist>`.
+
+The ``envoy_mobile_ios`` Bazel rule defined in the :repo:`dist BUILD file <dist/BUILD>` provides an
+example of how this artifact may be used.
+
+For a demo of a working app using this artifact, see the :ref:`hello_world` example.

docs/root/start/examples/hello_world.rst

@@ -0,0 +1,69 @@
+.. _hello_world:
+
+Hello World
+===========
+
+The "hello world" example project starts Envoy and uses it as a proxy for listening in
+on requests being made to a "hello world" endpoint on a 1 second timer.
+
+Upon receiving a response, the body text and ``Server`` header are displayed in a table.
+In the example output, you'll see that this header is set by Envoy:
+
+::
+
+    Response: Hello, world!
+    'Server' header: envoy
+
+You'll notice that the demo source code *doesn't directly call Envoy Mobile to perform
+API requests*.
+Instead, Envoy is started on app launch and listens in on requests/responses
+being made via the existing stack.
+Envoy Mobile will soon allow consumers to call directly into it (i.e., via ``envoy.request(...)``),
+but for these demos, it acts *purely as a proxy*.
+
+The demo is available below (along with building instructions) in the following languages:
+
+- `Java`_
+- `Objective-C`_
+- `Swift`_
+
+----
+Java
+----
+
+First, build the :ref:`android_aar` artifact (or download it from one of the recent releases_).
+
+Next, run the :repo:`sample app <examples/java/hello_world>` using the following Bazel build rule.
+Make sure you have an Android simulator running already:
+
+``bazel mobile-install //examples/java/hello_world:hello_envoy --fat_apk_cpu=x86``
+
+You should see a new app installed on your simulator called ``Hello Envoy``.
+Open it up, and requests will start flowing!
+
+-----------
+Objective-C
+-----------
+
+First, build the :ref:`ios_framework` artifact (or download it from one of the recent releases_).
+
+Next, run the :repo:`sample app <examples/objective-c/hello_world>` using the following Bazel build
+rule.
+
+``bazel run //examples/objective-c/hello_world:app --config=ios``
+
+This will start a simulator and open a new app. You should see requests start flowing!
+
+-----
+Swift
+-----
+
+First, build the :ref:`ios_framework` artifact (or download it from one of the recent releases_).
+
+Next, run the :repo:`sample app <examples/swift/hello_world>` using the following Bazel build rule.
+
+``bazel run //examples/swift/hello_world:app --config=ios``
+
+This will start a simulator and open a new app. You should see requests start flowing!
+
+.. _releases: https://github.com/lyft/envoy-mobile/releases

docs/root/start/start.rst

@@ -6,5 +6,5 @@ Getting Started
 .. toctree::
   :maxdepth: 2
 
-  android/android
-  ios/ios
+  building/building
+  examples/hello_world

examples/java/hello_world/README.md

@@ -0,0 +1 @@
+For instructions on how to use this demo, please head over to our [docs](https://envoy-mobile.github.io/docs/envoy-mobile/latest/start/examples/hello_world.html).

examples/objective-c/hello_world/README.md

@@ -1,5 +1 @@
-# Hello World example
-
-This example project starts the Envoy process and uses it as a proxy for listening in on requests being made to a "hello world" endpoint on a timer.
-
-Upon receiving a response, the details are logged to the console, and the response text and `Server` header are displayed in a table view in a native iOS app.
+For instructions on how to use this demo, please head over to our [docs](https://envoy-mobile.github.io/docs/envoy-mobile/latest/start/examples/hello_world.html).

examples/swift/hello_world/README.md

@@ -1,5 +1 @@
-# Hello World example
-
-This example project starts the Envoy process and uses it as a proxy for listening in on requests being made to a "hello world" endpoint on a timer.
-
-Upon receiving a response, the details are logged to the console, and the response text and `Server` header are displayed in a table view in a native iOS app.
+For instructions on how to use this demo, please head over to our [docs](https://envoy-mobile.github.io/docs/envoy-mobile/latest/start/examples/hello_world.html).