Add docs

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/.shared"]
+	path = docs/.shared
+	url = https://github.com/amphp/amphp.github.io

docs/.gitignore

@@ -0,0 +1,3 @@
+.bundle
+_site
+vendor

docs/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+gem "github-pages"
+gem "kramdown"
+gem "jekyll-github-metadata"
+gem "jekyll-relative-links"

docs/Gemfile.lock

@@ -0,0 +1,241 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.9)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
+    commonmarker (0.17.7.1)
+      ruby-enum (~> 0.5)
+    concurrent-ruby (1.0.5)
+    ethon (0.11.0)
+      ffi (>= 1.3.0)
+    execjs (2.7.0)
+    faraday (0.13.1)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.18)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.0)
+    github-pages (172)
+      activesupport (= 4.2.9)
+      github-pages-health-check (= 1.3.5)
+      jekyll (= 3.6.2)
+      jekyll-avatar (= 0.5.0)
+      jekyll-coffeescript (= 1.0.2)
+      jekyll-commonmark-ghpages (= 0.1.3)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.9.2)
+      jekyll-gist (= 1.4.1)
+      jekyll-github-metadata (= 2.9.3)
+      jekyll-mentions (= 1.2.0)
+      jekyll-optional-front-matter (= 0.3.0)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.2.0)
+      jekyll-redirect-from (= 0.12.1)
+      jekyll-relative-links (= 0.5.2)
+      jekyll-remote-theme (= 0.2.3)
+      jekyll-sass-converter (= 1.5.0)
+      jekyll-seo-tag (= 2.3.0)
+      jekyll-sitemap (= 1.1.1)
+      jekyll-swiss (= 0.4.0)
+      jekyll-theme-architect (= 0.1.0)
+      jekyll-theme-cayman (= 0.1.0)
+      jekyll-theme-dinky (= 0.1.0)
+      jekyll-theme-hacker (= 0.1.0)
+      jekyll-theme-leap-day (= 0.1.0)
+      jekyll-theme-merlot (= 0.1.0)
+      jekyll-theme-midnight (= 0.1.0)
+      jekyll-theme-minimal (= 0.1.0)
+      jekyll-theme-modernist (= 0.1.0)
+      jekyll-theme-primer (= 0.5.2)
+      jekyll-theme-slate (= 0.1.0)
+      jekyll-theme-tactile (= 0.1.0)
+      jekyll-theme-time-machine (= 0.1.0)
+      jekyll-titles-from-headings (= 0.5.0)
+      jemoji (= 0.8.1)
+      kramdown (= 1.14.0)
+      liquid (= 4.0.0)
+      listen (= 3.0.6)
+      mercenary (~> 0.3)
+      minima (= 2.1.1)
+      rouge (= 2.2.1)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.3.5)
+      addressable (~> 2.3)
+      net-dns (~> 0.8)
+      octokit (~> 4.0)
+      public_suffix (~> 2.0)
+      typhoeus (~> 0.7)
+    html-pipeline (2.7.1)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    i18n (0.9.1)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.6.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 1.1)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 3)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.5.0)
+      jekyll (~> 3.0)
+    jekyll-coffeescript (1.0.2)
+      coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
+    jekyll-commonmark (1.1.0)
+      commonmarker (~> 0.14)
+      jekyll (>= 3.0, < 4.0)
+    jekyll-commonmark-ghpages (0.1.3)
+      commonmarker (~> 0.17.6)
+      jekyll-commonmark (~> 1)
+      rouge (~> 2)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.9.2)
+      jekyll (~> 3.3)
+    jekyll-gist (1.4.1)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.9.3)
+      jekyll (~> 3.1)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-mentions (1.2.0)
+      activesupport (~> 4.0)
+      html-pipeline (~> 2.3)
+      jekyll (~> 3.0)
+    jekyll-optional-front-matter (0.3.0)
+      jekyll (~> 3.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.2.0)
+      jekyll (~> 3.0)
+    jekyll-redirect-from (0.12.1)
+      jekyll (~> 3.3)
+    jekyll-relative-links (0.5.2)
+      jekyll (~> 3.3)
+    jekyll-remote-theme (0.2.3)
+      jekyll (~> 3.5)
+      rubyzip (>= 1.2.1, < 3.0)
+      typhoeus (>= 0.7, < 2.0)
+    jekyll-sass-converter (1.5.0)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.3.0)
+      jekyll (~> 3.3)
+    jekyll-sitemap (1.1.1)
+      jekyll (~> 3.3)
+    jekyll-swiss (0.4.0)
+    jekyll-theme-architect (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-cayman (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-dinky (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-hacker (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-leap-day (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-merlot (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-midnight (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-minimal (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-modernist (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.5.2)
+      jekyll (~> 3.5)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.2)
+    jekyll-theme-slate (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.1.0)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.5.0)
+      jekyll (~> 3.3)
+    jekyll-watch (1.5.1)
+      listen (~> 3.0)
+    jemoji (0.8.1)
+      activesupport (~> 4.0, >= 4.2.9)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (>= 3.0)
+    kramdown (1.14.0)
+    liquid (4.0.0)
+    listen (3.0.6)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9.7)
+    mercenary (0.3.6)
+    mini_portile2 (2.3.0)
+    minima (2.1.1)
+      jekyll (~> 3.3)
+    minitest (5.10.3)
+    multipart-post (2.0.0)
+    net-dns (0.8.0)
+    nokogiri (1.8.1)
+      mini_portile2 (~> 2.3.0)
+    octokit (4.8.0)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    pathutil (0.16.1)
+      forwardable-extended (~> 2.6)
+    public_suffix (2.0.5)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rouge (2.2.1)
+    ruby-enum (0.7.1)
+      i18n
+    rubyzip (1.2.1)
+    safe_yaml (1.0.4)
+    sass (3.5.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sawyer (0.8.1)
+      addressable (>= 2.3.5, < 2.6)
+      faraday (~> 0.8, < 1.0)
+    terminal-table (1.8.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    thread_safe (0.3.6)
+    typhoeus (0.8.0)
+      ethon (>= 0.8.0)
+    tzinfo (1.2.4)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+  jekyll-github-metadata
+  jekyll-relative-links
+  kramdown
+
+BUNDLED WITH
+   1.15.1

docs/_config.yml

@@ -0,0 +1,24 @@
+kramdown:
+  input: GFM
+  toc_levels: 2..3
+
+baseurl: "/websocket"
+layouts_dir: ".shared/layout"
+includes_dir: ".shared/includes"
+
+exclude: ["Gemfile", "Gemfile.lock", "README.md", "vendor"]
+safe: true
+
+repository: amphp/websocket
+gems:
+ - "jekyll-github-metadata"
+ - "jekyll-relative-links"
+
+defaults:
+ - scope:
+     path: ""
+     type: "pages"
+   values:
+     layout: "docs"
+
+shared_asset_path: "/websocket/asset"

docs/asset

@@ -0,0 +1 @@
+.shared/asset

docs/index.md

@@ -0,0 +1,92 @@
+---
+title: Introduction
+permalink: /
+---
+`amphp/websocket` provides an asynchronous WebSocket client for PHP based on Amp.
+WebSockets are full-duplex communication channels, which are mostly used for realtime communication where the HTTP request / response cycle has too much overhead.
+They're also used if the server should be able to push data to the client without an explicit request.
+
+There are various use cases for a WebSocket client in PHP, such as consuming realtime APIs, writing tests for a WebSocket server, or controlling web browsers via their remote debugging APIs, which are based on WebSockets.
+
+## Connecting
+
+A new WebSocket connection is created using `Amp\Websocket\connect()`.
+It accepts a string as first argument, which must use the `ws` or `wss` (WebSocket over TLS) scheme.
+Further optional arguments are `ClientConnectContext`, `ClientTlsContext` and `Options`, which usually don't need to be customized.
+
+If you need to send additional headers with the initial handshake, you can pass a `Handshake` object as first argument instead of a string with the URL.
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use Amp\Websocket;
+
+Amp\Loop::run(function () {
+    /** @var Websocket\Connection $connection */
+    $connection = yield Websocket\connect('ws://localhost:1337/ws');
+
+    // do something
+});
+```
+
+## Sending Data
+
+WebSocket messages can be sent using the `send()` and `sendBinary()` methods.
+Text messages sent with `send()` must be valid UTF-8.
+Binary messages send with `sendBinary()` can be arbitrary data.
+
+Both methods return a `Promise` that is resolved as soon as the message is fully written to the send buffer. This doesn't neither mean that the message has been received by the other party nor that the message even left the local system's send buffer, yet.
+
+## Receiving Data
+
+WebSocket messages can be received using the `receive()` method. The `Promise` returned from `receive()` resolves once the client has started to receive a message. This allows streaming WebSocket messages, which might be pretty large. In practice, most messages are rather small, and it's fine buffering them completely. The `Promise` returned from `receive()` resolves to a `Message`, which allows easy buffered and streamed consumption.
+
+{:.note}
+> `Amp\Websocket\Message` differs from `Amp\ByteStream\Message`.
+> While `Amp\ByteStream\Message` directly implements `Promise`, this is not possible for promise resolution values.
+> Instead a consumer has to call `Amp\Websocket\Message::buffer()` which returns a `Promise` resolving to the entire message contents.
+>
+> A future version of `amphp/byte-stream` will change `Amp\ByteStream\Message` in a similar way or add a replacement.
+
+## Demo
+
+The following example connects to a WebSocket demo server that just echos all messages it receives.
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use Amp\Delayed;
+use Amp\Websocket;
+
+Amp\Loop::run(function () {
+    /** @var Websocket\Connection $connection */
+    $connection = yield Websocket\connect('ws://demos.kaazing.com/echo');
+    yield $connection->send('Hello!');
+
+    $i = 0;
+
+    /** @var Websocket\Message $message */
+    while ($message = yield $connection->receive()) {
+        $payload = yield $message->buffer();
+
+        printf("Received: %s\n", $payload);
+
+        if ($payload === 'Goodbye!') {
+            $connection->close();
+            break;
+        }
+
+        yield new Delayed(1000);
+
+        if ($i < 3) {
+            yield $connection->send('Ping: ' . ++$i);
+        } else {
+            yield $connection->send('Goodbye!');
+        }
+    }
+});
+```