Merge pull request #58 from php-http/doc-stubs

Add complete TOC and stubs
php-http · Jan 2, 2016 · 33c4aab · 33c4aab
2 parents 5946c4b + 6904910
commit 33c4aab
Show file tree

Hide file tree

Showing 28 changed files with 110 additions and 22 deletions.
diff --git a/docs/clients/curl-client.md b/docs/clients/curl-client.md
@@ -0,0 +1 @@
+# CURL Client
diff --git a/docs/clients/guzzle5-adapter.md b/docs/clients/guzzle5-adapter.md
@@ -0,0 +1 @@
+# Guzzle5 Adapter
diff --git a/docs/clients/guzzle6-adapter.md b/docs/clients/guzzle6-adapter.md
@@ -0,0 +1 @@
+# Guzzle6 Adapter
diff --git a/docs/clients/index.md b/docs/clients/index.md
@@ -0,0 +1,6 @@
+# Clients & Adapters
+
+There are clients implementing one of the HTTPlug interfaces directly,
+and adapter packages that implement the interface and forward the calls to HTTP clients not implementing the interface.
+
+TODO
diff --git a/docs/clients/mock-client.md b/docs/clients/mock-client.md
@@ -0,0 +1 @@
+# Mock Client
diff --git a/docs/clients/react-adapter.md b/docs/clients/react-adapter.md
@@ -0,0 +1 @@
+# React Adapter
diff --git a/docs/clients/socket-client.md b/docs/clients/socket-client.md
@@ -0,0 +1 @@
+# Socket Client
diff --git a/docs/components/adapter-integration-tests.md b/docs/components/adapter-integration-tests.md
@@ -0,0 +1,3 @@
+# Adapter Integration Tests
+
+TODO
diff --git a/docs/httplug/utils.md → docs/components/client-common.md b/docs/httplug/utils.md → docs/components/client-common.md
@@ -1,6 +1,7 @@
-# Utilities
+# Client Common
 
-The utilities package provides some useful tools for working with HTTPlug. Include them in your project with composer:
+The client-common package provides some useful tools for working with HTTPlug.
+Include them in your project with composer:
 
 ``` bash
 composer require "php-http/utils" "^1.0"

diff --git a/docs/components/authentication.md → docs/components/message.md b/docs/components/authentication.md → docs/components/message.md
@@ -1,19 +1,29 @@
-# Authentication
+# Message
+
+This package contains various PSR-7 tools which might be useful in an HTTP workflow:
+
+* Authentication method implementations
+* Various Stream encoding tools
+* Message decorators
+* Message factory implementations for Guzzle PSR-7 and Diactoros
+* Cookie implementation
+
+## Authentication
 
 The Authentication component allows you to to implement authentication methods which can simply update the request
 with authentication detail (for example by adding an `Authorization` header).
 This is useful when you have to send multiple requests to the same endpoint. Using an authentication implementation,
 these details can be separated from the actual requests.
 
 
-## Installation
+### Installation
 
 ```
 $ composer require php-http/message
 ```
 
 
-## Authentication methods
+### Authentication methods
 
 Method           | Parameters                                        | Behavior
 ---------------- | ------------------------------------------------- | --------
@@ -28,15 +38,15 @@ Matching         | An authentication instance and a matcher callback | Behavior
 [2]: http://www.xml.com/pub/a/2003/12/17/dive.html
 
 
-## Integration with HTTPlug
+### Integration with HTTPlug
 
 Normally requests must be authenticated "by hand" which is not really convenient.
 
 If you use HTTPlug, you can integrate this component into the client using the
 [authentication plugin](/httplug/plugins/authentication).
 
 
-## Examples
+### Examples
 
 General usage looks like the following:
 
@@ -48,7 +58,7 @@ $authentication->authenticate($request);
 ```
 
 
-### Basic Auth
+#### Basic Auth
 
 ``` php
 use Http\Message\Authentication\BasicAuth;
@@ -57,7 +67,7 @@ $authentication = new BasicAuth('username', 'password');
 ```
 
 
-### Bearer
+#### Bearer
 
 ``` php
 use Http\Message\Authentication\Bearer;
@@ -66,7 +76,7 @@ $authentication = new Bearer('token');
 ```
 
 
-### WSSE
+#### WSSE
 
 ``` php
 use Http\Message\Authentication\Wsse;
@@ -75,7 +85,7 @@ $authentication = new Wsse('username', 'password');
 ```
 
 
-### Query Params
+#### Query Params
 
 `http://api.example.com/endpoint?access_token=9zh987g86fg87gh978hg9g79`
 
@@ -94,7 +104,7 @@ $authentication = new QueryParams([
 
 
 
-### Chain
+#### Chain
 
 The idea behind this authentication method is that in some cases you might need to
 authenticate the request with multiple methods.
@@ -115,7 +125,7 @@ $authentication = new Chain($authenticationChain);
 ```
 
 
-### Matching
+#### Matching
 
 With this authentication method you can conditionally add authentication details to your request by passing a callable
 to it. When a request is passed, the callable is called and used as a boolean value in order to decide whether
@@ -152,7 +162,7 @@ $authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api'
 ```
 
 
-## Implement your own
+### Implement your own
 
 Implementing an authentication method is easy: only one method needs to be implemented.
 

diff --git a/docs/components/promise.md b/docs/components/promise.md
@@ -0,0 +1,5 @@
+# Promise
+
+Promise used for asynchronous HTTP requests.
+
+This will eventually be removed/deprecated and replaced with the upcoming Promise PSR.
diff --git a/docs/httplug/migrating.md b/docs/httplug/migrating.md
@@ -11,7 +11,7 @@ The monolithic ivory package has been separated into several smaller, more speci
 Instead of `Ivory\HttpAdapter\PsrHttpAdapter`, use `Http\Client\HttpClient`.
 The HttpClient simply has a method to send requests.
 
-If you used the `Ivory\HttpAdapter\HttpAdapter`, have a look at the [Utilities](utils.md)
+If you used the `Ivory\HttpAdapter\HttpAdapter`, have a look at [client-common](../components/client-common.md)
 and use the `Http\Client\Utils\HttpMethodsClient` which wraps any HttpClient and provides the convenience methods
 to send requests without creating RequestInterface instances.
 
@@ -22,9 +22,9 @@ Replace usage of `GuzzleHttp\ClientInterface` with `Http\Client\HttpClient`.
 The `send` method is called `sendRequest`.
 Instead of the `$options` argument, configure the client appropriately during set up.
 If you need different settings, create different instances of the client.
-You can use [plugins](plugins.md) to further tune your client.
+You can use [plugins](../plugins/index.md) to further tune your client.
 
-If you used the `request` method, have a look at the [Utilities](utils.md) and
+If you used the `request` method, have a look at [client-common](../components/client-common.md) and
 use the `Http\Client\Utils\HttpMethodsClient` which wraps any HttpClient and provides the convenience methods
 to send requests without creating RequestInterface instances.
 

diff --git a/docs/httplug/plugins/encoding.md b/docs/httplug/plugins/encoding.md
diff --git a/docs/httplug/plugins/authentication.md → docs/plugins/authentication.md b/docs/httplug/plugins/authentication.md → docs/plugins/authentication.md
@@ -19,5 +19,5 @@ $pluginClient = new PluginClient(
 );
 ```
 
-Check the [authentication component documentation](http://docs.httplug.io/en/latest/components/authentication/)
+Check the [authentication component documentation](../components/message.md#authentication)
 for the list of available authentication methods.
diff --git a/docs/plugins/cache.md b/docs/plugins/cache.md
@@ -0,0 +1,3 @@
+# Cache Plugin
+
+TODO
diff --git a/docs/plugins/content-length.md b/docs/plugins/content-length.md
@@ -0,0 +1,3 @@
+# Content-Length Plugin
+
+TODO
diff --git a/docs/httplug/plugins/cookie.md → docs/plugins/cookie.md b/docs/httplug/plugins/cookie.md → docs/plugins/cookie.md
diff --git a/docs/plugins/decoder.md b/docs/plugins/decoder.md
@@ -0,0 +1,3 @@
+# Decoder Plugin
+
+TODO
diff --git a/docs/httplug/plugins/error.md → docs/plugins/error.md b/docs/httplug/plugins/error.md → docs/plugins/error.md
diff --git a/docs/plugins/history.md b/docs/plugins/history.md
@@ -0,0 +1,3 @@
+# History Plugin
+
+TODO: explain the error plugin
diff --git a/docs/httplug/plugins.md → docs/plugins/index.md b/docs/httplug/plugins.md → docs/plugins/index.md
@@ -180,5 +180,5 @@ the core as small as possible with the most widely used plugin implementations.
 
 Even if we think that a plugin is not suitable for the core, we want to help you sharing your work with the community.
 You can always open a Pull Request to place a link and a small description of your plugin on the
-[Third Party Plugins](plugins/third-party-plugins.md) page. In special cases,
+[Third Party Plugins](third-party-plugins.md) page. In special cases,
 we might offer you to host your package under the PHP HTTP namespace.
diff --git a/docs/plugins/journal.md b/docs/plugins/journal.md
@@ -0,0 +1,3 @@
+# Journal
+
+TODO
diff --git a/docs/plugins/logger.md b/docs/plugins/logger.md
@@ -0,0 +1,3 @@
+# Logger Plugin
+
+TODO
diff --git a/docs/httplug/plugins/redirect.md → docs/plugins/redirect.md b/docs/httplug/plugins/redirect.md → docs/plugins/redirect.md
diff --git a/docs/httplug/plugins/retry.md → docs/plugins/retry.md b/docs/httplug/plugins/retry.md → docs/plugins/retry.md
diff --git a/docs/httplug/plugins/stopwatch.md → docs/plugins/stopwatch.md b/docs/httplug/plugins/stopwatch.md → docs/plugins/stopwatch.md
diff --git a/docs/httplug/plugins/third-party-plugins.md → docs/plugins/third-party-plugins.md b/docs/httplug/plugins/third-party-plugins.md → docs/plugins/third-party-plugins.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,3 +9,45 @@ markdown_extensions:
           permalink: true
     - sane_lists
     - admonition
+
+pages:
+    - Home: index.md
+    - HTTPlug:
+        - httplug/index.md
+        - httplug/migrating.md
+        - httplug/tutorial.md
+        - httplug/virtual-package.md
+    - Components:
+        - 'Clients & Adapters':
+            - Introduction: clients/index.md
+            - clients/curl-client.md
+            - clients/mock-client.md
+            - clients/socket-client.md
+            - clients/guzzle5-adapter.md
+            - clients/guzzle6-adapter.md
+            - clients/react-adapter.md
+        - Plugins:
+            - plugins/index.md
+            - plugins/authentication.md
+            - plugins/cache.md
+            - plugins/content-length.md
+            - plugins/cookie.md
+            - plugins/decoder.md
+            - plugins/error.md
+            - plugins/history.md
+            - plugins/journal.md
+            - plugins/logger.md
+            - plugins/redirect.md
+            - plugins/retry.md
+            - plugins/stopwatch.md
+            - plugins/third-party-plugins.md
+        - components/message.md
+        - Other Components:
+            - components/client-common.md
+            - components/discovery.md
+            - components/message-factory.md
+            - components/promise.md
+    - Development:
+        - development/code-of-conduct.md
+        - development/contributing.md
+        - development/license.md