Skip to content

Commit 9059cb7

Browse files
dbudbu
authored
Merge pull request #160 from php-http/doc-style-cleanup
cleanup documentation pages
2 parents a484ddb + 20b0de7 commit 9059cb7

17 files changed

+94
-90
lines changed

‎clients/buzz-adapter.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Or if you installed the :doc:`discovery </discovery>` layer::
5454

5555
The message factory parameter is mandatory if the discovery layer is not installed.
5656

57-
Be aware
57+
Be Aware
5858
--------
5959

6060
This adapter violates the Liskov substitution principle in a rare edge case. When the adapter is configured to use

‎clients/curl-client.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Or you can use :doc:`../discovery`::
3737

3838
$client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find());
3939

40-
Configuring client
40+
Configuring Client
4141
------------------
4242

4343
You can use `cURL options <http://php.net/curl_setopt>`_ to configure Client::

‎clients/mock-client.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ To install the Mock client, run:
1414
1515
$ composer require php-http/mock-client
1616
17-
Collect requests
17+
Collect Requests
1818
----------------
1919

2020
To make assertions::
@@ -40,7 +40,7 @@ To make assertions::
4040
}
4141
}
4242

43-
Fake responses and exceptions
43+
Fake Responses and Exceptions
4444
-----------------------------
4545

4646
Test how your code behaves when the HTTP client throws exceptions or returns

‎components/multipart-stream-builder.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ A multipart stream is a special kind of stream that is used to transfer files ov
3434
3535
In the request above you see a set of HTTP headers and a body with two streams. The body starts and ends with a "boundary" and it is also this boundary that separates the streams. That boundary also needs to be specified in the ``Content-Type`` header.
3636

37-
Building a multipart stream
37+
Building a Multipart Stream
3838
```````````````````````````
3939

4040
To build a multipart stream you may use the ``MultipartStreamBuilder``. It is not coupled to any stream implementation so it needs a ``StreamFactory`` to create the streams.

‎development/contributing.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Contributing
33

44
If you're here, you would like to contribute to this project and you're really welcome!
55

6-
Bug reports
6+
Bug Reports
77
-----------
88

99
If you find a bug or a documentation issue, please report it or even better: fix it :). If you report it,
@@ -14,15 +14,15 @@ please be as precise as possible. Here is a little list of required information:
1414
- Backtrace which might help identifying the bug
1515

1616

17-
Security issues
17+
Security Issues
1818
---------------
1919

2020
If you discover any security related issues,
2121
please contact us at [email protected] instead of submitting an issue on GitHub.
2222
This allows us to fix the issue and release a security hotfix without publicly disclosing the vulnerability.
2323

2424

25-
Feature requests
25+
Feature Requests
2626
----------------
2727

2828
If you think a feature is missing, please report it or even better: implement it :). If you report it, describe the more
@@ -86,7 +86,7 @@ If your branch conflicts with the master branch, you will need to rebase and re-
8686
$ git pull --rebase upstream master
8787
$ git push -f origin feature-or-bug-fix-description
8888
89-
Coding standard
89+
Coding Standard
9090
---------------
9191

9292
This repository follows the `PSR-2 standard`_ and so, if you want to contribute,

‎development/documentation.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Install Sphinx
88
--------------
99

1010

11-
Install on local machine
11+
Install on Local Machine
1212
~~~~~~~~~~~~~~~~~~~~~~~~
1313

1414
The installation for Sphinx differs between system. See `Sphinx installation page`_ for details. When Sphinx is
@@ -42,7 +42,7 @@ without entering the container shell:
4242
on the host too.
4343

4444

45-
Build documentation
45+
Build Documentation
4646
-------------------
4747

4848
Before we can build the documentation we have to make sure to install all requirements.

‎httplug/introduction.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ When all packages used in an application only specify HTTPlug,
77
the application developers can choose the client that best fits their project
88
and use the same client with all packages.
99

10-
The client interfaces
11-
---------------------
10+
Client Interfaces
11+
-----------------
1212

1313
HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
1414

‎httplug/library-developers.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
HTTPlug for library developers
1+
HTTPlug for Library Developers
22
==============================
33

44
If you’re developing a library or framework that performs HTTP requests, you
@@ -7,7 +7,7 @@ Instead, you should only make sure that *some* HTTP client is available. It is
77
then up to your users to decide which HTTP client they want to include in their
88
projects. This complies with the `dependency inversion principle`_.
99

10-
Manage dependencies
10+
Manage Dependencies
1111
-------------------
1212

1313
To depend on *some* HTTP client, specify either
@@ -78,14 +78,14 @@ If your library relies on specific plugins, the recommended way is to provide a
7878
your users, so they can create the correct client from a base HttpClient. See
7979
:ref:`plugin-client.libraries` for a concrete example.
8080

81-
User documentation
81+
User Documentation
8282
------------------
8383

8484
To explain to your users that they need to install a concrete HTTP client,
8585
you can point them to :doc:`users`.
8686

8787

88-
Your final ``composer.json``
88+
Your Final ``composer.json``
8989
----------------------------
9090

9191
Putting it all together your final ``composer.json`` is much likely to look similar to this:

‎httplug/tutorial.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
HTTPlug tutorial
1+
HTTPlug Tutorial
22
================
33

44
This tutorial should give you an idea how to use HTTPlug in your project. HTTPlug has two main use cases:
@@ -17,7 +17,7 @@ We use Composer_ for dependency management. Install it if you don't have it yet.
1717
there is an integration available. Framework integrations will simplify the way
1818
you set up clients, letting you focus on handling the requests.
1919

20-
Setting up the project
20+
Setting up the Project
2121
----------------------
2222

2323
.. code-block:: bash
@@ -32,7 +32,7 @@ The last command will install Guzzle as well as the Guzzle HTTPlug adapter and t
3232
We are now ready to start coding.
3333

3434

35-
Writing some simple code
35+
Writing Some Simple Code
3636
------------------------
3737

3838
Create a file ``demo.php`` in the root folder and write the following code::
@@ -43,7 +43,7 @@ Create a file ``demo.php`` in the root folder and write the following code::
4343
TODO: create client instance with discovery and do some requests
4444

4545

46-
Using an asynchronous client
46+
Using an Asynchronous Client
4747
----------------------------
4848

4949
Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Promise\Promise``::
@@ -53,10 +53,10 @@ Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Pr
5353
$httpAsyncClient = HttpAsyncClientDiscovery::find();
5454
$promise = $httpAsyncClient->sendAsyncRequest($request);
5555

56-
Using callback system
57-
^^^^^^^^^^^^^^^^^^^^^
56+
Using the Callback System
57+
^^^^^^^^^^^^^^^^^^^^^^^^^
5858

59-
This promise allows you to add callbacks for when the response is available or an errors happens by using the then method::
59+
The promise allows you to add callbacks for when the response is available or an errors happens by using the then method::
6060

6161
$promise->then(function (ResponseInterface $response) {
6262
// onFulfilled callback
@@ -161,7 +161,7 @@ Here is a full example of a classic usage when using the ``sendAsyncRequest`` me
161161
// Do your stuff with the response
162162
...
163163

164-
Handling errors
164+
Handling Errors
165165
---------------
166166

167167
TODO: explain how to handle exceptions, distinction between network exception and HttpException.

‎httplug/usage.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ HTTPlug is relevant for three groups of users:
66
.. toctree::
77
:maxdepth: 1
88

9-
Library users <users>
10-
Application developers <tutorial>
11-
Library developers <library-developers>
9+
Library Users <users>
10+
Application Developers <tutorial>
11+
Library Developers <library-developers>
1212

‎httplug/users.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ HTTP client in your project, Composer will throw an error:
7171
7272
You can solve this by including a HTTP client or adapter, as described above.
7373

74-
No message factories
74+
No Message Factories
7575
`````````````````````
7676

7777
You may get an exception telling you that "No message factories found", this

‎integrations/symfony-bundle.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ You can configure a client with authentication. Valid authentication types are `
223223
factory: 'httplug.factory.guzzle6'
224224
plugins: ['httplug.plugin.authentication.my_wsse']
225225
226-
Special HTTP clients
226+
Special HTTP Clients
227227
````````````````````
228228

229229
If you want to use the ``FlexibleHttpClient`` or ``HttpMethodsClient`` from the ``php-http/message`` package you may specify that on the client configuration.

‎message/authentication.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Installation
1414
1515
$ composer require php-http/message
1616
17-
Authentication methods
17+
Authentication Methods
1818
^^^^^^^^^^^^^^^^^^^^^^
1919

2020
+----------------+---------------------------------------------------+-----------------------------------------------------+
@@ -149,7 +149,7 @@ The first argument is an authentication method, the second is a regular expressi
149149
$authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api');
150150

151151

152-
Implement your own
152+
Implement Your Own
153153
^^^^^^^^^^^^^^^^^^
154154

155155
Implementing an authentication method is easy: only one method needs to be implemented::

‎plugins/build-your-own.rst

+10-7
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,16 @@ To better understand the whole process check existing implementations in the
9696
Contributing Your Plugins to PHP-HTTP
9797
-------------------------------------
9898

99-
We are open to contributions. If the plugin is of general interest, is not too complex and does not have dependencies, the best
100-
is to do a Pull Request to ``php-http/client-common``. Please see the :doc:`contribution guide <../development/contributing>`.
101-
We don't promise that every plugin gets merged into the core. We need to keep the core as small as
102-
possible with only the most widely used plugins to keep it maintainable.
103-
104-
The alternative is providing your plugins in your own repository. Please let us know when you do,
105-
we would like to add a list of existing third party plugins to the list of plugins.
99+
We are open to contributions. If the plugin is of general interest, not too
100+
complex and does not have dependencies, the best is to do a Pull Request to
101+
``php-http/client-common``. Please see the :doc:`contribution guide <../development/contributing>`.
102+
We don't promise that every plugin gets merged into the core. We need to keep
103+
the core as small as possible with only the most widely used plugins to keep
104+
it maintainable.
105+
106+
The alternative is providing your plugins in your own repository. Please let us
107+
know when you do, we would like to add a list of existing third party plugins
108+
to the list of plugins.
106109

107110
.. _PSR: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
108111
.. _client-common package: https://github.com/php-http/client-common

‎plugins/headers.rst

+18-23
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
Header Plugins
22
==============
33

4-
Header plugins are useful to manage request headers. Many operations are possible:
4+
Header plugins are useful to manage request headers. Many operations are
5+
possible with the provided plugins.
56

6-
Default headers values
7+
Default Headers Values
78
----------------------
89

9-
The plugin ``HeaderDefaultsPlugin`` allows you to set default values for given headers.
10-
That means if a header is not set, it will be added.
11-
However, if the header is already present, the request is left unchanged.
12-
13-
.. code:: php
10+
The plugin ``HeaderDefaultsPlugin`` allows you to define default values for
11+
given headers. If a header is not set, it will be added. However, if the header
12+
is already present, the request is left unchanged::
1413

1514
use Http\Discovery\HttpClientDiscovery;
1615
use Http\Client\Common\PluginClient;
@@ -27,11 +26,12 @@ However, if the header is already present, the request is left unchanged.
2726
[$headerDefaultsPlugin]
2827
);
2928

30-
Mandatory headers values
29+
Mandatory Headers Values
3130
------------------------
3231

33-
The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That means that any request passing through
34-
this plugin will have the given value for the given header.
32+
The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That
33+
means that any request passing through this plugin will be set to the specified
34+
value. Existing values of the header will be overwritten.
3535

3636
.. code:: php
3737
@@ -51,21 +51,17 @@ this plugin will have the given value for the given header.
5151
[$headerSetPlugin]
5252
);
5353
54-
55-
56-
Removing headers
54+
Removing Headers
5755
----------------
5856

59-
The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the request.
57+
The plugin ``HeaderRemovePlugin`` allows you to remove headers from the request.
6058

6159
.. code:: php
6260
6361
use Http\Discovery\HttpClientDiscovery;
6462
use Http\Client\Common\PluginClient;
6563
use Http\Client\Common\Plugin\HeaderRemovePlugin;
6664
67-
$userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
68-
6965
$headerRemovePlugin = new HeaderRemovePlugin([
7066
'User-Agent'
7167
]);
@@ -75,17 +71,17 @@ The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the re
7571
[$headerRemovePlugin]
7672
);
7773
78-
79-
Appending header values
74+
Appending Header Values
8075
-----------------------
8176

82-
The plugin ``HeaderAppendPlugin`` allows you to set headers or to add values to existing headers.
83-
That means if the request already has the given headers then the value will be appended to the current value
84-
but if the request does not already have the given header, it will be added to the request with the given value.
77+
The plugin ``HeaderAppendPlugin`` allows you to add headers. The header will be
78+
created if not existing yet. If the header already exists, the value will be
79+
appended to the list of values for this header.
8580

8681
.. note::
8782

88-
This plugin is very specific and is mostly useful for headers like "forwarded"
83+
The use cases for this plugin are limited. One real world example of
84+
headers that can have multiple values is "Forwarded".
8985

9086
.. code:: php
9187
@@ -104,7 +100,6 @@ but if the request does not already have the given header, it will be added to t
104100
[$headerAppendPlugin]
105101
);
106102
107-
108103
Mixing operations
109104
-----------------
110105

0 commit comments

Comments
 (0)