Build docs on Travis

Fix references to glossary

Clean up

Author: ddeboer

.travis.yml

@@ -17,8 +17,12 @@ before_script:
   - sh -c "if [ '$TRAVIS_PHP_VERSION' = 'hhvm' ]; then ./tests/ci/install-apache-hhvm.sh; fi"
   # Install deps
   - composer update --dev --prefer-source
+  # Install Sphinx
+  - sudo apt-get install python-sphinx
 
-script: phpunit --coverage-clover=coverage.clover
+script:
+  - phpunit --coverage-clover=coverage.clover
+  - make -C doc html
 
 after_script:
   - wget https://scrutinizer-ci.com/ocular.phar

doc/cache-invalidator.rst

@@ -29,8 +29,10 @@ Create the cache invalidator by passing a proxy client as
 Invalidating Paths and URLs
 ---------------------------
 
-Make sure to :doc:`configure your proxy <proxy-configuration>` for purging
-first.
+.. note::
+
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for purging
+    first.
 
 Invalidate a path:
 
@@ -51,8 +53,10 @@ Invalidate a URL:
 Refreshing Paths and URLs
 -------------------------
 
-Make sure to :doc:`configure your proxy <proxy-configuration>` for refreshing
-first.
+.. note::
+
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for refreshing
+    first.
 
 .. code-block:: php
 
@@ -68,7 +72,10 @@ Refresh a URL:
 Invalidating With a Regular Expression
 --------------------------------------
 
-Make sure to :doc:`configure your proxy <proxy-configuration>` for banning first.
+.. note::
+
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for banning
+    first.
 
 URL, Content Type and Hostname
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -84,7 +91,7 @@ caching proxy:
 
     $cacheInvalidator->invalidateRegex('.*css$')->flush();
 
-To invalidate all .png files for host example.com:
+To invalidate all .png files on host example.com:
 
 .. code-block:: php
 
@@ -96,9 +103,12 @@ To invalidate all .png files for host example.com:
 Any Header
 ~~~~~~~~~~
 
-You can also invalidate the cache based on any headers. If you use non-default
-headers, make sure to [configure your proxy accordingly](proxy-configuration.md)
-to have them taken into account.
+You can also invalidate the cache based on any headers.
+
+.. note::
+
+    If you use non-default headers, make sure to :doc:`configure your proxy <proxy-configuration>`
+    to have them taken into account.
 
 Cache client implementations should fill up the headers to at least have the
 default headers always present to simplify the cache configuration rules.
@@ -111,14 +121,17 @@ To invalidate on a custom header ``X-My-Header``, you would do:
 
 .. _tags:
 
-Tags
-----
+Invalidating Tags
+-----------------
+
+.. note::
 
-Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging first.
+    Make sure to :doc:`configure your proxy <proxy-configuration>` for tagging first.
 
-You will have to make sure your web application adds the correct tags on all
-responses by setting the ``X-Cache-Tags`` header. The FOSHttpCacheBundle_ does
-does this for you when you’re using Symfony.
+With tags you can group related representations so it becomes easier to
+invalidate them. You will have to make sure your web application adds the
+correct tags on all responses by setting the ``X-Cache-Tags`` header. The
+FOSHttpCacheBundle_ does does this for you when you’re using Symfony.
 
 Assume you sent four responses:
 

doc/conf.py

@@ -37,16 +37,16 @@
 
 # General information about the project.
 project = 'FOSHttpCache'
-copyright = '2014, David Buchmann, David de Boer'
+copyright = '2014, FriendsOfSymfony'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '1.0.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+release = '1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -116,7 +116,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/invalidation-introduction.rst

@@ -2,8 +2,7 @@ An Introduction to Cache Invalidation
 =====================================
 
 This general introduction explains cache invalidation concepts. If you are
-already familiar with cache invalidation, you may wish to skip this chapter
-and continue to the [Cache Invalidator](cache-invalidator.md).
+already familiar with cache invalidation, you may wish to skip this chapter.
 
 HTTP Caching Terminology
 ------------------------
@@ -44,7 +43,7 @@ The problem
 HTTP caching is a great solution for improving the performance of your web
 application. For lower load on the application and fastest response time, you
 want to cache content for a long period. But at the same time, you want your
-clients see fresh content as soon as there was an update.
+clients to see fresh content as soon as there is an update.
 
 Instead of finding some compromise, you can have both with cache invalidation.
 When application data changes, the application takes care of invalidating its
@@ -91,7 +90,7 @@ Cache invalidation has two possible downsides:
   changed, a lot more is involved in invalidating all of its representations.
   In other words, invalidation adds a layer of complexity to your application.
   This library tries to help reduce complexity, for instance by
-  [tagging](#tags) cached content. Additionally, if you use Symfony2, we
+  :ref:`tagging <tags>` cached content. Additionally, if you use Symfony2, we
   recommend you use the FOSHttpCacheBundle_.
   which provides additional functionality to make invalidation easier.
 * Invalidation is done through requests to your caching proxy. Sending these

doc/nginx-configuration.rst

@@ -8,7 +8,7 @@ features provided by this library. The examples are tested with Nginx version
 Purge
 ~~~~~
 
-Nginx does not support :ref:`purge requests <purge>` out of the box. The
+Nginx does not support :term:`purge` requests out of the box. The
 `ngx_cache_purge <https://github.com/FRiCKLE/ngx_cache_purge>`_ adds some support.
 
 .. note::
@@ -41,7 +41,7 @@ for more on configuring Nginx to support purge requests.
 Refresh
 ~~~~~~~
 
-If you want to invalidate cached objects by :ref:`forcing a refresh <refresh>`
+If you want to invalidate cached objects by forcing a :term:`refresh`
 you have to use the built-in `proxy_cache_bypass <http://wiki.nginx.org/HttpProxyModule#proxy_cache_bypass/>`_
 operation.
 

doc/testing-your-application.rst

@@ -43,16 +43,12 @@ Setting Constants
 
 Compare this library’s configuration to see how the constants are set:
 
-.. code-block:: xml
-
-    <?xml version="1.0" encoding="UTF-8"?>
-
-    <phpunit ...>
-        <php>
-            <const name="VARNISH_FILE" value="./tests/FOS/HttpCache/Tests/Functional/Fixtures/varnish/fos.vcl" />
-            <const name="WEB_SERVER_HOSTNAME" value="localhost" />
-        </php>
-    </phpunit>
+.. literalinclude:: ../phpunit.xml.dist
+    :prepend:
+        <?xml version="1.0" encoding="UTF-8"?>
+        <phpunit ...>
+    :language: xml
+    :start-after: <php>
 
 Overriding Getters
 ~~~~~~~~~~~~~~~~~~
@@ -117,7 +113,8 @@ correctly:
 
     public function testCachePurge()
     {
-        // Again, Varnish is restarted, so your test is independent
+        // Again, Varnish is restarted, so your test is independent from
+        // other tests
 
         $url = '/blog/articles/1';