Merge pull request #327 from FriendsOfSymfony/docs

Fix some documentation issues

Author: dbu

doc/_static/fos.css

@@ -1,3 +1,7 @@
 .versionmodified {
     font-weight: bold;
 }
+
+span.pre {
+    color: #404040;
+}

doc/cache-invalidator.rst

@@ -45,9 +45,7 @@ Invalidating Paths and URLs
 
 Invalidate a path::
 
-    $cacheInvalidator->invalidatePath('/users')
-        ->flush()
-    ;
+    $cacheInvalidator->invalidatePath('/users')->flush();
 
 See below for the :ref:`flush() <flush>` method.
 

doc/contributing.rst

@@ -1,9 +1,9 @@
 Contributing
 ============
 
-We are happy for contributions. Before you invest a lot of time however, best
-open an issue on GitHub_ to discuss your idea. Then we can coordinate efforts
-if somebody is already working on the same thing.
+We warmly welcome contributions to FOSHttpCache. Before you invest a lot of time
+however, please open an issue on GitHub_ to discuss your idea. Then we can
+coordinate efforts if somebody is already working on the same thing.
 
 Testing the Library
 -------------------

doc/installation.rst

@@ -4,8 +4,8 @@ Getting started
 Installation
 ------------
 
-The FOSHttpCache library is available on Packagist_. You can install it using
-Composer_.
+The FOSHttpCache library is available on Packagist_. You can install the library
+and its dependencies using Composer_.
 
 The library relies on HTTPlug_ for sending invalidation requests over HTTP, so
 you need to install an HTTPlug-compatible client or adapter first:
@@ -37,10 +37,7 @@ Then install the FOSHttpCache library itself:
 .. note::
 
     This library follows `Semantic Versioning`_.  Except for major versions, we
-    aim to not introduce BC breaks in new releases. You should still test your
-    application after upgrading though. What is a bug fix for somebody could
-    break something for others when they where (probably unawares) relying on
-    that bug.
+    aim to not introduce BC breaks in new releases.
 
 Configuration
 -------------

doc/nginx-configuration.rst

@@ -8,21 +8,21 @@ features provided by this library. The examples are tested with NGINX version
 1.4.6.
 
 NGINX cache is a set of key/value pairs. The key is built with elements taken from the requests
-(URI, cookies, http headers etc) as specified by `proxy_cache_key` directive.
+(URI, cookies, http headers etc) as specified by ``proxy_cache_key`` directive.
 
 When we interact with the cache to purge/refresh entries we must send to NGINX a request which has
 the very same values, for the elements used for building the key, as the request that create the entry.
 In this way NGINX can build the correct key and apply the required operation to the entry.
 
-By default NGINX key is built with `$scheme$proxy_host$request_uri`. For a full list of the elements
-you can use in the key see `this page from the official documentation <http://nginx.org/en/docs/http/ngx_http_core_module.html#variables>`_
+By default NGINX key is built with ``$scheme$proxy_host$request_uri``. For a full list of the elements
+you can use in the key see `this page from the official documentation <http://nginx.org/en/docs/http/ngx_http_core_module.html#variables>`_.
 
 Purge
 ~~~~~
 
 NGINX does not support :term:`purge` functionality out of the box but you can easily add it with
 `ngx_cache_purge <https://github.com/FRiCKLE/ngx_cache_purge>`_ module. You just need to compile
-NGINX from sources adding `ngx_cache_purge` with `--add-module`
+NGINX from sources adding ``ngx_cache_purge`` with ``--add-module``.
 
 You can check the script :source:`install-nginx.sh <tests/install-nginx.sh>` to get an idea
 about the steps you need to perform.
@@ -55,7 +55,7 @@ so add a line like the following to your config:
 Debugging
 ~~~~~~~~~
 
-Configure your Nginx to set a custom header (`X-Cache`) that shows whether a
+Configure your Nginx to set a custom header (``X-Cache``) that shows whether a
 cache hit or miss occurred:
 
 .. code-block:: none

doc/proxy-clients.rst

@@ -16,8 +16,8 @@ client suitable for the proxy server you use.
 Supported invalidation methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Not all clients support all operations. This table provides an overview what
-each proxy client supports:
+Not all clients support all :ref:`invalidation methods <invalidation methods>`.
+This table provides of methods supported by each proxy client:
 
 ============= ======= ======= =======
 Client        Purge   Refresh Ban
@@ -35,7 +35,7 @@ Setup
 -----
 
 Most proxy clients use the ``HttpDispatcher`` to send requests to the proxy
-server. The ``HttpDispatcher`` is built on top of the Httplug_ abstraction to
+server. The ``HttpDispatcher`` is built on top of the HTTPlug_ abstraction to
 be independent of specific HTTP client implementations.
 
 .. _HTTP client configuration:
@@ -69,10 +69,10 @@ used. If you specify a custom HTTP client, you need to configure the client to
 convert HTTP error status into exceptions. This can either be done in a client
 specific way or with the HTTPlug ``PluginClient`` and the ``ErrorPlugin``.
 If client and/or URI factory are not specified, the dispatcher uses
-`Httplug discovery_` to find available implementations.
+`HTTPlug discovery`_ to find available implementations.
 
-Learn more about available HTTP clients `in the Httplug documentation`_. To
-customize the behavior of the HTTP client, you can use `Httplug plugins`_.
+Learn more about available HTTP clients `in the HTTPlug documentation`_. To
+customize the behavior of the HTTP client, you can use `HTTPlug plugins`_.
 
 .. _varnish client:
 
@@ -104,7 +104,7 @@ You can also pass some options to the Varnish client:
   merged with the built-in headers.
 
 Additionally, you can specify the request factory used to build the
-invalidation HTTP requests. If not specified, auto discovery is used - which
+invalidation HTTP requests. If not specified, auto discovery is used – which
 usually is fine.
 
 A full example could look like this::
@@ -175,7 +175,7 @@ The Multiplexer client allows multiple Proxy clients to be used during the stand
 cache invalidation, thus enabling multiple caches to be handled at once.
 It is useful when multiple caches exist in the environment and they need to be handled
 at the same time; the Multiplexer proxy client will forward the cache invalidation calls
-to all Proxy clients provided at creation time.::
+to all proxy clients provided at creation time::
 
     use FOS\HttpCache\ProxyClient\MultiplexerClient;
     use FOS\HttpCache\ProxyClient\Nginx;
@@ -215,8 +215,8 @@ requests to the proxy server. This is on purpose: this way, we can send
 all requests together, reducing the performance impact of sending invalidation
 requests.
 
-.. _Httplug: http://httplug.io/
-.. _Httplug discovery: http://php-http.readthedocs.io/en/latest/discovery.html
-.. _in the Httplug documentation: http://php-http.readthedocs.io/en/latest/clients.html
-.. _Httplug plugins: http://php-http.readthedocs.io/en/latest/plugins/index.html
+.. _HTTPlug: http://httplug.io/
+.. _HTTPlug discovery: http://php-http.readthedocs.io/en/latest/discovery.html
+.. _in the HTTPlug documentation: http://php-http.readthedocs.io/en/latest/clients.html
+.. _HTTPlug plugins: http://php-http.readthedocs.io/en/latest/plugins/index.html
 .. _message factory and URI factory: http://php-http.readthedocs.io/en/latest/message/message-factory.html

doc/proxy-configuration.rst

@@ -3,7 +3,8 @@
 Proxy Server Configuration
 ==========================
 
-You need to configure the proxy server of your choice. These guides help you
+You need to configure the proxy server of your choice (Varnish, NGINX or Symfony
+HttpCache) to work with FOSHttpCache. These guides help you
 for the configuration for the features of this library. You will still need to
 know about the other features of the proxy server to get everything right.
 

doc/symfony-cache-configuration.rst

@@ -3,7 +3,7 @@
 Symfony HttpCache Configuration
 -------------------------------
 
-The ``symfony/http-kernel`` component provides a reverse proxy implemented
+Symfony’s `HttpKernel`_ component provides a reverse proxy implemented
 completely in PHP, called `HttpCache`_. While it is certainly less efficient
 than using Varnish or NGINX, it can still provide considerable performance
 gains over an installation that is not cached at all. It can be useful for
@@ -264,3 +264,4 @@ something went really wrong in the kernel. Have a look at ``X-Symfony-Cache``
 and at the HTML body of the response.
 
 .. _HttpCache: http://symfony.com/doc/current/book/http_cache.html#symfony-reverse-proxy
+.. _HttpKernel: http://symfony.com/doc/current/components/http_kernel.html

doc/testing-your-application.rst

@@ -143,7 +143,7 @@ to test both Varnish 3 and 4 on a continuous integration system). See the
 ==================== ========================= ======= ===========================================
 Environment Variable Getter                    Default Description
 ==================== ========================= ======= ===========================================
-``VARNISH_VERSION``  ``getVarnishVersion()``   ``4``   version of varnish application that is used
+``VARNISH_VERSION``  ``getVarnishVersion()``   ``4``   version of Varnish application that is used
 ==================== ========================= ======= ===========================================
 
 See ``tests/bootstrap.php`` for an example how this repository uses the version
@@ -224,7 +224,7 @@ CacheAssertions Trait
 
 Provides cache hit/miss assertions to your tests. To enable the these
 ``assertHit`` and ``assertMiss`` assertions, you need to configure your proxy
-server to set an `X-Cache` header with the cache status:
+server to set an ``X-Cache`` header with the cache status:
 
 * :ref:`Varnish <varnish_debugging>`
 * :ref:`NGINX <nginx_debugging>`

doc/varnish-configuration.rst

@@ -33,7 +33,7 @@ simple ACL, valid for all Varnish versions from 3 onwards, looks as follows:
     trigger invalidation are whitelisted here. Otherwise, lost cache invalidation
     requests will lead to lots of confusion.
 
-Provided Vcl Subroutines
+Provided VCL Subroutines
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to ease configuration we provide a set of VCL subroutines in the