diff --git a/.travis.yml b/.travis.yml index aa5f29b7..c855abdb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -36,6 +36,7 @@ before_script: - composer update --dev --prefer-source # Install Sphinx - sudo apt-get install python-sphinx + - sudo pip install -r doc/requirements.txt script: - phpunit --coverage-clover=coverage.clover diff --git a/doc/_static/tabs.css b/doc/_static/tabs.css new file mode 100644 index 00000000..5477e27e --- /dev/null +++ b/doc/_static/tabs.css @@ -0,0 +1,98 @@ +div.configuration-block { + position: relative; +} + +div.configuration-block ul.simple { + margin-left: 38px; +} + +div.configuration-block ul.simple li { + list-style: none; + float: left; + margin-left: 0; + margin-right: 1em; + padding: .2em .5em .5em .5em; + height: 38px; + background-color: #c9c9c9; +} + +div.configuration-block ul.simple li.selected { + background-color: #343131; + border-bottom: none; +} + +div.configuration-block ul.simple li.selected a { + color: white; +} + +div.highlight-varnish3, div.highlight-varnish4 { + border: none !important; +} + +div.configuration-block em { + font-style: normal; +} + +div.configuration-block div { + border-top: none; + position: absolute; + left: 0; + width: 100%; + max-width: 100%; + overflow: auto; +} + +div.configuration-block div div { + position: static; +} + +div.highlight { + background-color: #343131 !important; +} + +div.highlight pre { + border: none; + color: white; +} + +div.highlight pre span.n, +div.highlight pre span.na, +div.highlight pre span.nb, +div.highlight pre span.nc, +div.highlight pre span.nf, +div.highlight pre span.nx { + color: white; +} + +div.highlight pre span.nv { + color: #6ab0de +} + +div.highlight pre span.k, div.highlight pre span.o { + color: #ff8400; +} + +div.highlight pre span.mi, +div.highlight pre span.s, +div.highlight pre span.s1, +div.highlight pre span.s2, +div.highlight pre span.sr { + color: #56db3a; +} + +div.highlight pre span.hll { + background-color: #848484; +} + +div.highlight pre span.p { + color: #b3b3b3; +} + +table.highlighttable td { + padding: 0; +} + +table.highlighttable td div.linenodiv { + text-align: right; + width: 38px; +} diff --git a/doc/_static/tabs.js b/doc/_static/tabs.js new file mode 100644 index 00000000..2852ee64 --- /dev/null +++ b/doc/_static/tabs.js @@ -0,0 +1 @@ +$(document).ready(function(){$("div.configuration-block [class^=highlight-]").hide();$("div.configuration-block").addClass("jsactive");$("div.configuration-block").addClass("clearfix");$("div.configuration-block").each(function(){var a=$("[class^=highlight-]:first",$(this));a.show();a.parents("ul:eq(0)").height(a.height()+40)});$("div.configuration-block li").each(function(){var a=$(":first",$(this)).html();$(":first ",$(this)).html("");$(":first ",$(this)).append(''+a+"");$(":first",$(this)).bind("click",function(){$("[class^=highlight-]",$(this).parents("ul")).hide();$("li",$(this).parents("ul")).removeClass("selected");$(this).parent().addClass("selected");var b=$("[class^=highlight-]",$(this).parent("li"));b.show();b.parents("ul:eq(0)").height(b.height()+40);return false})});$("div.configuration-block").each(function(){$("li:first",$(this)).addClass("selected")})}); diff --git a/doc/conf.py b/doc/conf.py index 550e9934..a1280d1c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -5,16 +5,21 @@ import sys, os from sphinx.highlighting import lexers from pygments.lexers.web import PhpLexer +from pygments.lexers.compiled import CLexer lexers['php'] = PhpLexer(startinline=True, linenos=1) +lexers['varnish3'] = CLexer() +lexers['varnish4'] = CLexer() + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + primary_domain = 'php' highlight_language = 'php' -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -22,7 +27,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.coverage', 'sphinx.ext.extlinks'] +extensions = ['sphinx.ext.coverage', 'sphinx.ext.extlinks', 'sensio.sphinx.configurationblock'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -86,10 +91,6 @@ # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. @@ -117,7 +118,11 @@ # 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'] + +def setup(app): + app.add_javascript('tabs.js') + app.add_stylesheet('tabs.css') # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -244,3 +249,7 @@ extlinks = {'source': ('https://github.com/FriendsOfSymfony/FOSHttpCache/blob/master/%s', '') } +config_block = { + 'varnish3': 'Varnish 3', + 'varnish4': 'Varnish 4' +} diff --git a/doc/testing-the-library.rst b/doc/contributing.rst similarity index 75% rename from doc/testing-the-library.rst rename to doc/contributing.rst index 10e3028e..e677c2e0 100644 --- a/doc/testing-the-library.rst +++ b/doc/contributing.rst @@ -1,5 +1,8 @@ +Contributing +============ + Testing the Library -=================== +------------------- This chapter describes how to run the tests that are included with this library. @@ -13,7 +16,7 @@ First clone the repository, install the vendors, then run the tests: $ phpunit Unit Tests ----------- +~~~~~~~~~~ To run the unit tests separately: @@ -22,7 +25,7 @@ To run the unit tests separately: $ phpunit tests/Unit Functional Tests ----------------- +~~~~~~~~~~~~~~~~ The library also includes functional tests against a Varnish instance. The functional test suite by default uses PHP’s built-in web server. If you have @@ -43,5 +46,24 @@ To run the functional tests: For more information about testing, see :doc:`/testing-your-application`. +Building the Documentation +-------------------------- + +First `install Sphinx`_, then download the requirements: + +.. code-block:: bash + + $ pip install -r doc/requirements.txt + +To build the docs: + +.. code-block:: bash + + $ cd doc + $ make html + .. _HHVM: http://www.hhvm.com/ .. _HHVM FastCGI server: https://github.com/facebook/hhvm/wiki/fastcgi +.. _install Sphinx: http://sphinx-doc.org/latest/install.html + + diff --git a/doc/index.rst b/doc/index.rst index 7cb2f1eb..ae3539d7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -24,4 +24,4 @@ Contents: user-context testing-your-application - testing-the-library + contributing diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..e9a779af --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +git+https://github.com/fabpot/sphinx-php.git +sphinx-rtd-theme==0.1.6 diff --git a/doc/varnish-configuration.rst b/doc/varnish-configuration.rst index 4e32c744..de7a17a3 100644 --- a/doc/varnish-configuration.rst +++ b/doc/varnish-configuration.rst @@ -16,15 +16,15 @@ to your Varnish configuration. This ACL determines which IPs are allowed to issue invalidation requests. Let’s call the ACL `invalidators`. The ACL below will be used throughout the Varnish examples on this page. -.. code-block:: c +.. code-block:: varnish4 # /etc/varnish/your_varnish.vcl acl invalidators { - "localhost"; - # Add any other IP addresses that your application runs on and that you - # want to allow invalidation requests from. For instance: - # "192.168.1.0"/24; + "localhost"; + # Add any other IP addresses that your application runs on and that you + # want to allow invalidation requests from. For instance: + # "192.168.1.0"/24; } .. important:: @@ -40,17 +40,16 @@ To configure Varnish for `handling PURGE requests `_: -Varnish 3 -""""""""" +.. configuration-block:: -.. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl - :language: c - :lines: 1-7, 15-18, 20- + .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl + :language: varnish4 + :lines: 1-7, 15-18, 20- + :linenos: -Varnish 4 -""""""""" - -.. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl - :language: c - :lines: 1-7, 15-18, 20- + .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl + :language: varnish3 + :lines: 1-7, 15-18, 20- + :linenos: Varnish contains a `ban lurker`_ that crawls the content to eventually throw out banned data even when it’s not requested by any client. @@ -99,22 +94,18 @@ Add the following to your Varnish configuration to enable :ref:`cache tagging `. - -Varnish 3 -""""""""" - -.. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl - :language: c - :emphasize-lines: 8-13 - :linenos: - -Varnish 4 -""""""""" - -.. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl - :language: c - :emphasize-lines: 8-13 - :linenos: + +.. configuration-block:: + + .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl + :language: varnish4 + :emphasize-lines: 8-13 + :linenos: + + .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl + :language: varnish3 + :emphasize-lines: 8-13 + :linenos: .. _varnish user context: @@ -124,19 +115,16 @@ User Context To support :doc:`user context hashing ` you need to add some logic to the ``recv`` and the ``deliver`` methods: -Varnish 3 -""""""""" - -.. literalinclude:: ../tests/Functional/Fixtures/varnish-3/user_context.vcl - :language: c - :linenos: +.. configuration-block:: -Varnish 4 -""""""""" + .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/user_context.vcl + :language: varnish4 + :lines: 3- + :linenos: -.. literalinclude:: ../tests/Functional/Fixtures/varnish-4/user_context.vcl - :language: c - :linenos: + .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/user_context.vcl + :language: varnish3 + :linenos: .. sidebar:: Caching User Specific Content @@ -185,9 +173,10 @@ not be cached, but multiple hashes would be generated for one and the same user. To make the hash request cacheable, you must extract a stable user session id. You can do this as -`explained in the varnish documentation `_: +`explained in the Varnish documentation `_: -.. code-block:: c +.. code-block:: varnish4 + :linenos: sub vcl_recv { # ... @@ -211,19 +200,17 @@ You can do this as Debugging ~~~~~~~~~ -Varnish 3 -""""""""" - Configure your Varnish to set a debug header that shows whether a cache hit or miss occurred: -.. literalinclude:: ../tests/Functional/Fixtures/varnish-3/debug.vcl - :language: c +.. configuration-block:: -Varnish 4 -""""""""" + .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/debug.vcl + :language: varnish4 + :linenos: -.. literalinclude:: ../tests/Functional/Fixtures/varnish-4/debug.vcl - :language: c + .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/debug.vcl + :language: varnish3 + :linenos: .. _`default VCL`: https://www.varnish-cache.org/trac/browser/bin/varnishd/default.vcl?rev=3.0#L63