From bf4b6cf755b6e9731708074c05e082a8f0ae77fa Mon Sep 17 00:00:00 2001 From: David de Boer Date: Tue, 28 Oct 2014 23:49:10 +0100 Subject: [PATCH] Show VCL in tabs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add sphinx-php to pip requirements for building on RTD Rename ‘Testing the Library’ to ‘Contributing’ Add JS and CS for tabs * Make syntax highlighting resemble that of Symfony docs more. Remove fabpot/sphinx-php from require-dev * Now in requirements.txt Improve styling Add pip install to Travis Try to fix static path on RTD Run pip install as sudo on Travis Make border none important Revert path to static Move pip install to install steps Clean up tabs.js Remove sys.path.insert Switch from RubyLexer to CLexer Add link to Sphinx installation Remove duplicated html_theme Show Varnish 4 first --- .travis.yml | 1 + doc/_static/tabs.css | 98 ++++++++++++++ doc/_static/tabs.js | 1 + doc/conf.py | 31 +++-- ...sting-the-library.rst => contributing.rst} | 28 +++- doc/index.rst | 2 +- doc/requirements.txt | 2 + doc/varnish-configuration.rst | 121 ++++++++---------- 8 files changed, 202 insertions(+), 82 deletions(-) create mode 100644 doc/_static/tabs.css create mode 100644 doc/_static/tabs.js rename doc/{testing-the-library.rst => contributing.rst} (75%) create mode 100644 doc/requirements.txt 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