Allow ./docs to be published as Jekyll page

.gitmodules

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

docs/.gitignore

@@ -0,0 +1,2 @@
+.bundle
+_site

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,202 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.8)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.5.1)
+      public_suffix (~> 2.0, >= 2.0.2)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.12.2)
+    colorator (1.1.0)
+    ethon (0.10.1)
+      ffi (>= 1.3.0)
+    execjs (2.7.0)
+    faraday (0.12.1)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.18)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.0)
+    github-pages (138)
+      activesupport (= 4.2.8)
+      github-pages-health-check (= 1.3.3)
+      jekyll (= 3.4.3)
+      jekyll-avatar (= 0.4.2)
+      jekyll-coffeescript (= 1.0.1)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.9.2)
+      jekyll-gist (= 1.4.0)
+      jekyll-github-metadata (= 2.3.1)
+      jekyll-mentions (= 1.2.0)
+      jekyll-optional-front-matter (= 0.1.2)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.1.0)
+      jekyll-redirect-from (= 0.12.1)
+      jekyll-relative-links (= 0.4.0)
+      jekyll-sass-converter (= 1.5.0)
+      jekyll-seo-tag (= 2.2.3)
+      jekyll-sitemap (= 1.0.0)
+      jekyll-swiss (= 0.4.0)
+      jekyll-theme-architect (= 0.0.4)
+      jekyll-theme-cayman (= 0.0.4)
+      jekyll-theme-dinky (= 0.0.4)
+      jekyll-theme-hacker (= 0.0.4)
+      jekyll-theme-leap-day (= 0.0.4)
+      jekyll-theme-merlot (= 0.0.4)
+      jekyll-theme-midnight (= 0.0.4)
+      jekyll-theme-minimal (= 0.0.4)
+      jekyll-theme-modernist (= 0.0.4)
+      jekyll-theme-primer (= 0.1.8)
+      jekyll-theme-slate (= 0.0.4)
+      jekyll-theme-tactile (= 0.0.4)
+      jekyll-theme-time-machine (= 0.0.4)
+      jekyll-titles-from-headings (= 0.1.5)
+      jemoji (= 0.8.0)
+      kramdown (= 1.13.2)
+      liquid (= 3.0.6)
+      listen (= 3.0.6)
+      mercenary (~> 0.3)
+      minima (= 2.1.1)
+      rouge (= 1.11.1)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.3.3)
+      addressable (~> 2.3)
+      net-dns (~> 0.8)
+      octokit (~> 4.0)
+      public_suffix (~> 2.0)
+      typhoeus (~> 0.7)
+    html-pipeline (2.6.0)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    i18n (0.8.1)
+    jekyll (3.4.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 1.1)
+      kramdown (~> 1.3)
+      liquid (~> 3.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (~> 1.7)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.4.2)
+      jekyll (~> 3.0)
+    jekyll-coffeescript (1.0.1)
+      coffee-script (~> 2.2)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.9.2)
+      jekyll (~> 3.3)
+    jekyll-gist (1.4.0)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.3.1)
+      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.1.2)
+      jekyll (~> 3.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.1.0)
+      jekyll (~> 3.0)
+    jekyll-redirect-from (0.12.1)
+      jekyll (~> 3.3)
+    jekyll-relative-links (0.4.0)
+      jekyll (~> 3.3)
+    jekyll-sass-converter (1.5.0)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.2.3)
+      jekyll (~> 3.3)
+    jekyll-sitemap (1.0.0)
+      jekyll (~> 3.3)
+    jekyll-swiss (0.4.0)
+    jekyll-theme-architect (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-cayman (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-dinky (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-hacker (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-leap-day (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-merlot (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-midnight (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-minimal (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-modernist (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-primer (0.1.8)
+      jekyll (~> 3.3)
+    jekyll-theme-slate (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-tactile (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-theme-time-machine (0.0.4)
+      jekyll (~> 3.3)
+    jekyll-titles-from-headings (0.1.5)
+      jekyll (~> 3.3)
+    jekyll-watch (1.5.0)
+      listen (~> 3.0, < 3.1)
+    jemoji (0.8.0)
+      activesupport (~> 4.0)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (>= 3.0)
+    kramdown (1.13.2)
+    liquid (3.0.6)
+    listen (3.0.6)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9.7)
+    mercenary (0.3.6)
+    mini_portile2 (2.1.0)
+    minima (2.1.1)
+      jekyll (~> 3.3)
+    minitest (5.10.2)
+    multipart-post (2.0.0)
+    net-dns (0.8.0)
+    nokogiri (1.7.2)
+      mini_portile2 (~> 2.1.0)
+    octokit (4.7.0)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    pathutil (0.14.0)
+      forwardable-extended (~> 2.6)
+    public_suffix (2.0.5)
+    rb-fsevent (0.9.8)
+    rb-inotify (0.9.8)
+      ffi (>= 0.5.0)
+    rouge (1.11.1)
+    safe_yaml (1.0.4)
+    sass (3.4.24)
+    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.3)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+  jekyll-github-metadata
+  jekyll-relative-links
+  kramdown
+
+BUNDLED WITH
+   1.15.0

docs/README.md

@@ -2,13 +2,19 @@
 
 This directory contains the documentation for `amphp/amp`. Documentation and code are bundled within a single repository for easier maintenance. Additionally, this preserves the documentation for older versions.
 
-## Managing Concurrency
+## Reading
 
-The weak link when managing concurrency is humans; we simply don't think asynchronously or in parallel. Instead, we're really good at doing one thing at a time and the world around us generally fits this model. So to effectively design for concurrent processing in our code we have a couple of options:
+You can read this documentation either directly on GitHub or on our website. While the website will always contain the latest version, viewing on GitHub also works with older versions.
 
-1. Get smarter (not feasible);
-2. Abstract concurrent task execution to make it feel synchronous.
+## Writing
 
-Amp provides an [event loop](./event-loop/README.md), [promises](./promises/README.md) and [asynchronous iterators](./iterators/README.md) as building blocks for (fully) asynchronous libraries and applications. [Coroutines](./coroutines/README.md) make asynchronous code feel as synchronous as synchronous code.
+Our documentation is built using Jekyll.
 
-Start with the [Introduction to Event Loops](./event-loop/).
+```
+sudo gem install bundler jekyll
+```
+
+```
+bundle install --path vendor/bundle
+bundle exec jekyll serve
+```

docs/_config.yml

@@ -0,0 +1,13 @@
+kramdown:
+  input: GFM
+  toc_levels: 2..3
+
+baseurl: "/amp"
+layouts_dir: shared/layout
+
+exclude: ["Gemfile", "Gemfile.lock", "README.md", "vendor"]
+
+repository: amphp/amp
+gems:
+ - "jekyll-github-metadata"
+ - "jekyll-relative-links"

docs/cancellation/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /cancellation/
+---
 # Cancellation
 
 Amp provides primitives to allow the cancellation of operations, namely `CancellationTokenSource` and `CancellationToken`.
@@ -6,4 +10,5 @@ Every operation that supports cancellation accepts an instance of `CancellationT
   
 The original caller creates a `CancellationToken` by creating an instance of `CancellationTokenSource` and passing `$cancellationTokenSource->getToken()` to the operation. Only the original caller has access to the `CancellationTokenSource` and can cancel the operation using `CancellationTokenSource::cancel()`.
 
-> **Note:** Cancellations are advisory only and have don't care semantics. A DNS resolver might ignore cancellation requests after the query has been sent as the response has to be processed anyway and can still be cached. An HTTP client might continue a nearly finished HTTP request to reuse the connection, but might abort a chunked encoding response as it cannot know the end.
+{:.note}
+> Cancellations are advisory only and have don't care semantics. A DNS resolver might ignore cancellation requests after the query has been sent as the response has to be processed anyway and can still be cached. An HTTP client might continue a nearly finished HTTP request to reuse the connection, but might abort a chunked encoding response as it cannot know the end.

docs/coroutines/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /coroutines/
+---
 # Coroutines
 
 Coroutines are interruptible functions. In PHP they can be implemented using [generators](http://php.net/manual/en/language.generators.overview.php).
@@ -43,7 +47,3 @@ Loop::run(function () {
 ```
 
 Note that **no callbacks need to be registered** to consume promises and **errors can be handled with ordinary `catch` clauses**, which will bubble up to the calling context if uncaught in the same way exceptions bubble up in synchronous code.
-
-## Further Reading
-
- * [Coroutine Helpers](./helpers.md)

docs/coroutines/helpers.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /coroutines/helpers
+---
 # Coroutine Helpers
 
 `Amp\Coroutine` requires a already instantiated `Generator` to be passed to its constructor. Always calling a callable before passing the `Generator` to `Amp\Coroutine` is unnecessary boilerplate.

docs/event-loop/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /event-loop/
+---
 # Event Loop
 
 It may surprise people to learn that the PHP standard library already has everything we need to write event-driven and non-blocking applications. We only reach the limits of native PHP's functionality in this area when we ask it to poll thousands of file descriptors for IO activity at the same time. Even in this case, though, the fault is not with PHP but the underlying system `select()` call which is linear in its performance degradation as load increases.

docs/event-loop/api.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /event-loop/api
+---
 # Event Loop API
 
 This document describes the [`Amp\Loop`](../../lib/Loop.php) accessor. You might want to also read the documentation contained in the source file, it's extensively documented and doesn't contain much distracting code.
@@ -393,7 +397,3 @@ Loop::disable($watcherId);
 ### Timer Drift
 
 Repeat timers are basically simple delay timers that are automatically rescheduled right before the appropriate handler is triggered. They are subject to timer drift. Multiple timers might stack up in case they execute as coroutines.
-
-## Further Reading
-
-Continue with [Promises](../promises/README.md).

docs/index.md

@@ -0,0 +1,14 @@
+---
+layout: docs
+permalink: /
+---
+## Managing Concurrency
+
+The weak link when managing concurrency is humans; we simply don't think asynchronously or in parallel. Instead, we're really good at doing one thing at a time and the world around us generally fits this model. So to effectively design for concurrent processing in our code we have a couple of options:
+
+1. Get smarter (not feasible);
+2. Abstract concurrent task execution to make it feel synchronous.
+
+Amp provides an [event loop](./event-loop/README.md), [promises](./promises/README.md) and [asynchronous iterators](./iterators/README.md) as building blocks for (fully) asynchronous libraries and applications. [Coroutines](./coroutines/README.md) make asynchronous code feel as synchronous as synchronous code.
+
+Start with the [Introduction to Event Loops](./event-loop/).

docs/iterators/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /iterators/
+---
 # Iterators
 
 Iterators are the next level after promises. While promises resolve once and with one value, iterators allow a set of items to be consumed.
@@ -68,8 +72,3 @@ function fromIterable($iterable, int $delay = 0) { ... }
 ```
 
 `$delay` allows adding a delay between each emission.
-
-## Further Reading
-
- * [Iterator Combination](./combinators.md)
- * [Iterator Transformation](./transformation.md)

docs/iterators/combinators.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /iterators/combinators
+---
 # Iterator Combination
 
 Amp provides two common combination helpers for iterators: `concat` and `merge`.
@@ -9,7 +13,3 @@ Amp provides two common combination helpers for iterators: `concat` and `merge`.
 ## `merge()`
 
 `merge()` accepts an array of `Iterator` instances and creates an `Iterator` that emits values emitted from any iterator in the array of iterators ending once all emitters completed.
-
-## Further Reading
-
- * [Iterator Transformation](./transformation.md)

docs/iterators/transformation.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /iterators/transformation
+---
 # Iterator Transformation
 
 Amp provides two common transformation helpers for iterators: `map` and `filter`.
@@ -11,7 +15,3 @@ Further primitives are very easy to implement using `Producer` with those two as
 ## `filter()`
 
 `filter()` accepts an `Iterator` and a `callable` `$filter`. If `$filter($value)` returns `false` the value gets filtered, otherwise the value is retained in the resulting `Iterator`.
-
-## Further Reading
-
- * [Iterator Combination](./combinators.md)

docs/promises/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /promises/
+---
 # Promises
 
 The basic unit of concurrency in Amp applications is the `Amp\Promise`. These objects should be thought of as placeholders for values or tasks that aren't yet complete. By using placeholders we're able to reason about the results of concurrent operations as if they were already complete variables.
@@ -96,8 +100,3 @@ var_dump($result); // int(42)
 ### Success and Failure
 
 Sometimes values are immediately available. This might be due to them being cached, but can also be the case if an interface mandates a promise to be returned to allow for async I/O but the specific implementation always having the result directly available. In these cases `Amp\Success` and `Amp\Failure` can be used to construct a immediately resolved promise. `Amp\Success` accepts a resolution value. `Amp\Failure` accepts an exception as failure reason.
-
-## Further Reading
-
- * [Promise Combination](./combinators.md)
- * [Other Promise Helpers](./miscellaneous.md)

docs/promises/combinators.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /promises/combinators
+---
 # Promise Combinators
 
 Multiple promises can be combined into a single promise using different functions.
@@ -68,7 +72,3 @@ in the component arrays are preserved from the promise array passed to the funct
 
 `Amp\Promise\first()` resolves with the first successful result. The resulting promise will only fail if all
 promises in the group fail or if the promise array is empty.
-
-## Further Reading
-
- * [Other Promise Helpers](./miscellaneous.md)

docs/promises/miscellaneous.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /promises/miscellaneous
+---
 # Promise Helpers
 
 Amp offers some small promise helpers, namely
@@ -20,7 +24,3 @@ Note that `timeout()` does not cancel any operation or frees any resources. If a
 ## `wait()`
 
 `wait()` can be used to synchronously wait for a promise to resolve. It returns the result value or throws an exception in case of an error. `wait()` blocks and calls `Loop::run()` internally. It SHOULD NOT be used in fully asynchronous applications, but only when integrating async APIs into an otherwise synchronous application.
-
-## Further Reading
-
- * [Promise Combination](./combinators.md)

docs/shared

@@ -0,0 +1 @@
+Subproject commit d806819f1f5a242dd12b7b1102721ec2ae9d6c72

docs/utils/README.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /utils/
+---
 # Utils
 
 This documentation section deals with helpers that are not async specific, but generic helpers.

docs/utils/callable-maker.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /utils/callable-maker
+---
 # CallableMaker
 
 `Amp\CallableMaker` is a helper trait that allows creating closures from private / protected static and instance methods in an easy way. Creating such callables might be necessary to register private / protected methods as callbacks in an efficient manner without making those methods public.
@@ -11,7 +15,3 @@ Creates a `Closure` form an instance method with the given name and returns it.
 ## `callableFromStaticMethod()`
 
 Same as `callableFromInstanceMethod()`, but for static methods.
-
-## Further Reading
-
- * [`Struct`](./struct.md)

docs/utils/struct.md

@@ -1,3 +1,7 @@
+---
+layout: docs
+permalink: /utils/struct
+---
 # Struct
 
 A struct is a generic computer science term for an object composed of public properties. The `\Amp\Stuct` trait
@@ -42,7 +46,3 @@ The message for the thrown `\Error` will be similar to:
 
 Although, an `\Error` being thrown in your code may cause some havoc, it will not allow for unpredictable
 behavior caused by the use of properties which are not part of the class definition.
-
-## Further Reading
-
- * [`CallableMaker`](./callable-maker.md)