Add Usage docs (#79)

* Build main page with hugo and hyde theme to match opencensus.io style

* Add content for framework integration

* Fix code fence blocks

* Add pages for integrating Guzzle and Wordpress

* Add a page for using the extension

* Menu links

Author: chingor13

.travis.yml

@@ -4,8 +4,11 @@ php:
 
 install:
   - wget -O sami.phar http://get.sensiolabs.org/sami.phar
+  - wget -O /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v0.30.2/hugo_0.30.2_Linux-64bit.deb
+  - sudo dpkg -i /tmp/hugo.deb
 
 script:
+  - cd docs && hugo
   - php sami.phar update config/sami.php
   - touch docs/.nojekyll
 
@@ -15,7 +18,7 @@ branches:
 
 deploy:
   provider: pages
-  local_dir: docs
+  local_dir: docs/public
   skip_cleanup: true
   email: chingor@google.com # To satisfy the CLA check, replace this with bot email.
   github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard

config/sami.php

@@ -36,7 +36,7 @@
 
 $sami = new Sami($iterator, [
     // 'versions'  => $versions,
-    'build_dir' => __DIR__ . '/../docs',
+    'build_dir' => __DIR__ . '/../docs/public/api',
     'title' => 'OpenCensus PHP API'
 ]);
 

docs/.gitignore

@@ -0,0 +1,3 @@
+_site
+.sass-cache
+public/

docs/config.toml

@@ -0,0 +1,15 @@
+baseURL = "/"
+languageCode = "en-us"
+title = "OpenCensus for PHP"
+theme = "hyde"
+
+pygmentsCodeFences = true
+pygmentsOptions = "startinline=false"
+
+[params]
+  description = "A stats collection and distributed tracing framework"
+
+[[menu.main]]
+  name = "API Documentation"
+  url = "/api"
+  weight = -10

docs/content/index.md

@@ -0,0 +1,44 @@
+---
+title: "OpenCensus for PHP"
+date: "2017-11-30"
+type: index
+menu:
+  main:
+    weight: -100
+---
+
+# OpenCensus for PHP
+
+[API Documentation][api-docs]
+
+## Installation
+
+1. Install the `opencensus/opencensus` package using [composer][composer]:
+
+    ```bash
+    $ composer require opencensus/opencensus
+    ```
+
+1. [Optional]: Install the `opencensus` extension from [PECL][pecl]. See more
+   information on [using the extension](using-the-extension).
+
+## Tracing
+
+### Framework Integration
+
+* [Laravel](integrating-laravel)
+* [Silex](integrating-silex)
+* [Symfony](integrating-symfony)
+* [Wordpress](integrating-wordpress)
+
+### Other Integrations
+
+* [Guzzle](integrating-guzzle)
+
+## Stats
+
+Coming Soon!
+
+[api-docs]: api/
+[composer]: https://getcomposer.org/
+[pecl]: https://pecl.php.net/

docs/content/integrating-guzzle.md

@@ -0,0 +1,49 @@
+---
+title: "Integrating OpenCensus with Guzzle"
+date: "2017-11-30"
+type: page
+menu:
+  main:
+    parent: "Integrations"
+---
+
+Integration with Guzzle using the following methods will:
+
+1. Create spans for every outgoing HTTP request used by that Guzzle client.
+2. Propagate the span context to the remote endpoint for distributed tracing.
+
+## Guzzle 6
+
+To add OpenCensus support for Guzzle 6 HTTP clients, we add a middleware to our
+Guzzle client:
+
+```php
+<?php
+use GuzzleHttp\Client;
+use GuzzleHttp\HandlerStack;
+use OpenCensus\Trace\Integrations\Guzzle\Middleware;
+
+$stack = new HandlerStack();
+$stack->setHandler(\GuzzleHttp\choose_handler());
+$stack->push(new Middleware());
+$client = new Client(['handler' => $stack]);
+```
+
+You will want to set this up wherever your Guzzle client is created.
+
+## Guzzle 5
+
+To add OpenCensus support for Guzzle 5 clients, we attach an EventSubscriber to
+our Guzzle client:
+
+```php
+<?php
+use GuzzleHttp\Client;
+use OpenCensus\Trace\Integrations\Guzzle\EventSubscriber;
+
+$client = new Client();
+$subscriber = new EventSubscriber();
+$client->getEmitter()->attach($subscriber);
+```
+
+You will want to set this up wherever your Guzzle client is created.

docs/content/integrating-laravel.md

@@ -0,0 +1,63 @@
+---
+title: "Integrating OpenCensus with Laravel"
+date: "2017-11-30"
+type: page
+menu:
+  main:
+    parent: "Integrations"
+---
+
+## Laravel 5.5
+
+1. To add OpenCensus to our Laravel application, we will create a
+   `ServiceProvider`. In `app/Providers/OpenCensusProvider.php`:
+
+    ```php
+    <?php
+    namespace App\Providers;
+
+    use Illuminate\Support\ServiceProvider;
+    use OpenCensus\Trace\Exporter\StackdriverExporter;
+    use OpenCensus\Trace\Tracer;
+    use OpenCensus\Trace\Integrations\Laravel;
+    use OpenCensus\Trace\Integrations\Mysql;
+    use OpenCensus\Trace\Integrations\PDO;
+
+    class OpenCensusProvider extends ServiceProvider
+    {
+        public function boot()
+        {
+            if (php_sapi_name() == 'cli') {
+                return;
+            }
+
+            // Enable OpenCensus extension integrations
+            Laravel::load();
+            Mysql::load();
+            PDO::load();
+
+            // Start the request tracing for this request
+            $exporter = new StackdriverExporter();
+            Tracer::start($exporter);
+
+            // Create a span that starts from when Laravel first boots (public/index.php)
+            Tracer::inSpan(['name' => 'bootstrap', 'startTime' => LARAVEL_START], function () {});
+        }
+    }
+    ```
+
+    In this example, we configured `StackdriverExporter`, but you can configure
+    any exporter here. You can also enable any other integrations here.
+
+1. Enable this `ServiceProvider`. In `config/app.php`:
+
+    ```php
+    <?php
+    // in the `providers` section
+    ...
+    'providers' => [
+        ...
+        App\Providers\OpenCensusProvider::class,
+    ],
+    ...
+    ```

docs/content/integrating-silex.md

@@ -0,0 +1,28 @@
+---
+title: "Integrating OpenCensus with Silex"
+date: "2017-11-30"
+type: page
+menu:
+  main:
+    parent: "Integrations"
+---
+
+## Silex 2.2
+
+To add OpenCensus to our Silex application, we simply start the tracer at the
+beginning of our application. In `web/index.php`:
+
+```php
+<?php
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// Configure and start the OpenCensus Tracer
+$exporter = new OpenCensus\Trace\Exporter\StackdriverExporter();
+OpenCensus\Trace\Tracer::start($exporter);
+
+$app = new Silex\Application();
+// ... rest of the application
+```
+
+In this example, we configured `StackdriverExporter`, but you can configure
+any exporter here. You can also enable any other integrations here.

docs/content/integrating-symfony.md

@@ -0,0 +1,67 @@
+---
+title: "Integrating OpenCensus with Symfony"
+date: "2017-11-30"
+type: page
+menu:
+  main:
+    parent: "Integrations"
+---
+
+## Symfony 3.3
+
+1. To add OpenCensus to our Symfony application, we will create a `Bundle`
+   In `src/AppBundle/OpenCensusBundle.php`:
+
+    ```php
+    <?php
+    namespace AppBundle;
+
+    use OpenCensus\Trace\Exporter\StackdriverExporter;
+    use OpenCensus\Trace\Integrations\Mysql;
+    use OpenCensus\Trace\Integrations\PDO;
+    use OpenCensus\Trace\Integrations\Symfony;
+    use OpenCensus\Trace\Tracer;
+    use Symfony\Component\HttpKernel\Bundle\Bundle;
+
+    class AppBundle extends Bundle
+    {
+        public function boot()
+        {
+            $this->setupOpenCensus();
+        }
+
+        private function setupOpenCensus()
+        {
+            if (php_sapi_name() == 'cli') {
+                return;
+            }
+
+            // Enable OpenCensus extension integrations
+            Mysql::load();
+            PDO::load();
+            Symfony::load();
+
+            // Start the request tracing for this request
+            $exporter = new StackdriverExporter();
+            Tracer::start($exporter);
+        }
+    }
+    ```
+
+    In this example, we configured `StackdriverExporter`, but you can configure
+    any exporter here. You can also enable any other integrations here.
+
+1. Enable this `Bundle` by adding it to the list of bundles registered. In
+   `app/AppKernel.php`:
+
+    ```php
+    <?php
+    // in the `registerBundles()`
+    ...
+    $bundles = [
+        ...
+        new AppBundle\AppBundle(),
+        new AppBundle\OpenCensusBundle(),
+    ];
+    ...
+    ```

docs/content/integrating-wordpress.md

@@ -0,0 +1,29 @@
+---
+title: "Integrating OpenCensus with WordPress"
+date: "2017-11-30"
+type: page
+menu:
+  main:
+    parent: "Integrations"
+---
+
+To add OpenCensus to your WordPress installation, ensure that you can use
+composer with your instance of WordPress.
+
+In your `wp-config.php`:
+
+```php
+<?php
+// load composer dependencies
+require_once('/path/to/vendor/autoload.php');
+
+use OpenCensus\Trace\Exporter\StackdriverExporter;
+use OpenCensus\Trace\Tracer;
+
+OpenCensus\Trace\Integrations\Wordpress::load();
+$exporter = new StackdriverExporter();
+Tracer::start($exporter);
+```
+
+In this example, we configured `StackdriverExporter`, but you can configure any
+exporter here. You can also enable any other integrations here.