Merge HTTPlug intro and re-group TOC

Author: ddeboer

clients.rst

@@ -4,7 +4,9 @@ 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
+.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
+.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:
+
 
 Clients:
 

conf.py

@@ -301,4 +301,5 @@
 rst_epilog = """
 .. _PSR-7: http://www.php-fig.org/psr/psr-7
 .. _Composer: https://getcomposer.org
+.. _HttplugBundle: https://github.com/php-http/HttplugBundle
 """

httplug.rst

@@ -1,32 +1,48 @@
-Introduction to HTTPlug
-=======================
+HTTPlug: HTTP client abstraction
+================================
 
-HTTPlug implementations
------------------------
+HTTPlug allows you to write reusable libraries and applications that need
+an HTTP client without binding to a specific implementation.
+When all packages used in an application only specify HTTPlug,
+the application developers can choose the client that best fits their project
+and use the same client with all packages.
+
+The client interfaces
+---------------------
+
+HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
+
+* ``HttpClient`` defines a ``sendRequest`` method that sends a PSR-7
+  ``RequestInterface`` and either returns a PSR-7 ``ResponseInterface`` or
+  throws an exception that implements ``Http\Client\Exception``.
+
+* ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
+  asynchronously and always returns a ``Http\Client\Promise``.
 
-HTTPlug implementations typically are either HTTP clients of their own, or adapters wrapping existing clients
-like Guzzle 6. In the latter case, they will depend on the required client implementation,
-so you only need to require the adapter and not the actual client.
+Implementations
+---------------
 
+PHP-HTTP offers two types of clients that implement the above interfaces:
 
-There are two kind of implementations:
+1. Standalone clients that directly implement the interfaces.
 
- - `php-http/client-implementation`_:
-   the synchronous implementation that waits for the response / error before returning from the ``sendRequest`` method.
+   Examples: :doc:`/clients/curl-client` and :doc:`/clients/socket-client`.
 
- - `php-http/async-client-implementation`_:
-   the asynchronous implementation that immediately returns a ``Http\Promise\Promise``,
-   allowing to send several requests in parallel and handling responses later.
+2. Adapters that wrap existing HTTP client, such as Guzzle. These adapters act
+   as a bridge between the HTTPlug interfaces and the clients that do not (yet)
+   implement these interfaces.
 
-Check links above for the full list of implementations.
+   Examples: :doc:`/clients/guzzle6-adapter` and :doc:`/clients/react-adapter`.
 
-.. _`php-http/client-implementation`: https://packagist.org/providers/php-http/client-implementation
-.. _`php-http/async-client-implementation`: https://packagist.org/providers/php-http/async-client-implementation:
+.. note::
+
+    Ideally, all HTTP client libraries out there will implement the HTTPlug
+    interfaces. At that point, our adapters will no longer be necessary.
 
 Usage in an application
 -----------------------
 
-When writing an application, you need to require a concrete implementation_.
+When writing an application, you need to require a concrete implementation.
 
 See :doc:`virtual-package` for more information on the topic of working with HTTPlug implementations.
 
@@ -69,27 +85,20 @@ Best point them to the :doc:`virtual-package` page.
 To be able to send requests, you should not depend on a specific PSR-7 implementation,
 but use the :ref:`message-factory` system.
 
-Framework Integration
-^^^^^^^^^^^^^^^^^^^^^
-
-HTTPlug can be used in any PHP based project.
-Nonetheless, we provide particular integration for some popular frameworks:
-
-- HttplugBundle_: integration with the Symfony framework.
-
 History
 -------
 
-This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It never made it to a stable release,
-but it relied on PSR-7 which was not stable either that time. Because of the constantly changing PSR-7,
-Eric had to rewrite the library over and over again (at least the message handling part,
-which in most cases affected every adapter as well).
+This project has been started by `Eric Geloen`_ as `Ivory Http Adapter`_. It
+never made it to a stable release, but it relied on PSR-7 which was not stable
+either that time. Because of the constantly changing PSR-7, Eric had to rewrite
+the library over and over again (at least the message handling part, which in
+most cases affected every adapter as well).
 
-In 2015, a decision has been made to move the library to its own organization, so PHP HTTP was born.
+In 2015, a decision has been made to move the library to its own organization,
+so PHP-HTTP was born.
 
-See :doc:`migrating` for a guide how to migrate your code from the Ivory adapter to HTTPlug.
+See :doc:`migrating` for a guide how to migrate your code from the Ivory
+adapter.
 
-.. _implementation: https://packagist.org/providers/php-http/client-implementation
-.. _HttplugBundle: https://github.com/php-http/HttplugBundle
 .. _`Eric Geloen`: https://github.com/egeloen
-.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter).
+.. _`Ivory Http Adapter`: https://github.com/egeloen/ivory-http-adapter

httplug/introduction.rst

@@ -0,0 +1,17 @@
+Usage
+=====
+
+HTTPlug is an abstraction for HTTP clients. There are two main use cases:
+
+1. Usage in a project/application
+2. Usage in a reusable package
+
+
+Framework Integration
+^^^^^^^^^^^^^^^^^^^^^
+
+HTTPlug can be used in any PHP based project.
+Nonetheless, we provide particular integration for some popular frameworks:
+
+- HttplugBundle_: integration with the Symfony framework.
+

httplug/usage.rst

@@ -29,17 +29,7 @@ HTTPlug abstracts from HTTP clients written in PHP, offering a simple interface.
 It also provides an implementation-independent plugin system to build pipelines
 regardless of the HTTP client implementation used.
 
-HTTPlug allows you to write reusable libraries and applications that need
-an HTTP client without binding to a specific implementation.
-When all packages used in an application only specify HTTPlug,
-the application developers can choose the client that best fits their project
-and use the same client with all packages.
-
-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.
-
-Get started by reading our :doc:`tutorial </httplug/tutorial>`.
+Read more about :doc:`HTTPlug </httplug/introduction>`.
 
 Packages
 --------
@@ -64,17 +54,19 @@ for discussion around a future HTTP client PSR.
 
 .. toctree::
     :hidden:
-    :maxdepth: 3
 
     PHP-HTTP <self>
 
 .. toctree::
    :hidden:
-
-   HTTPlug <httplug>
-
-.. toctree::
-   :hidden:
+   :caption: HTTPlug
+   :maxdepth: 4
+
+   Introduction <httplug/introduction>
+   Usage <httplug/usage>
+   Tutorial <httplug/tutorial>
+   Migrating <httplug/migrating>
+   Virtual package <httplug/virtual-package>
 
    clients
    plugins/index