outdated varnish config in cookbook article

[dbu]

the cookbook article http://symfony.com/doc/current/cookbook/cache/varnish.html currently provides vcl examples for varnish 2 with commented out varnish 3 options (with a bug: in varnish 3, purge should also be called in vcl_miss - its point is to remove all variants from the cache, even if its not all matching). also, the vcl example is first shown without acl (dangerous) and then just below duplicated with the vcl. and we completely miss varnish 4 docs.

i would like to do a PR to clean that up. ideally we could have config tabs for the vcl, like we have for xml / yaml / php config or twig / php templating. a while ago i opened fabpot/sphinx-php#16 (also talking about literalinclude which is not relevant here.) any chance we could do something like that? showing 3 versions of vcl mixed together, or one below the other, is not elegant.

[ddeboer]

👍

[xabbuh]

i would like to do a PR to clean that up. ideally we could have config tabs for the vcl, like we have for xml / yaml / php config or twig / php templating. a while ago i opened fabpot/sphinx-php#16 (also talking about literalinclude which is not relevant here.) any chance we could do something like that? showing 3 versions of vcl mixed together, or one below the other, is not elegant.

Adding other tabs to a configuration-block isn't that hard. Basically, we would have to configure lexers in conf.py like this:

from pygments.lexers.special import TextLexer

lexers['vcl2'] = TextLexer()
lexers['vcl3'] = TextLexer()
lexers['vcl4'] = TextLexer()

This would then be used like this:

.. configuration-block::

    .. code-block:: vcl2

        Varnish2 config

    .. code-block:: vcl3

        Varnish3 config

    .. code-block:: vcl4

        Varnish4 config

There is only some little work necessary to render the appropriate tab levels in the produced HTML.

[weaverryan]

Hey guys!

I definitely think our Varnish documentation (and caching docs in general) are one of our weakest spots. I agree with you that having the tabs would be best, but I would rather get things fixed than wait for this to happen (if at all).

So, could we get things fixed up without the tabs? Could we emphasize Varnish 4.0 code first, with little comments for any 3.0 and 2.0 changes? Do we even need to show 2.0 anymore? Even 3.0 has been out since June 2011?

Thanks for opening this @dbu!

[dbu]

i had this idea to review the whole caching chapter and try to do a PR cleaning it up. but atm i am still travelling and had no time to do it. i think varnish 4 is not yet widely used - people tend to be conservative with these tools ;-) so 3 and 4 seem equally important to me. varnish 2 would be ok to keep but f.ex. in FOSHttpCacheBundle we did not bother, i guess its better to drop it.

without the tabs it will be harder to read, but i guess we can find a way with a note for lines to change.

so if you want to start something, go ahead - otherwise i try a big overhaul in october :-)

[weaverryan]

I really do want this, but I think you have more experience than I do with it. If you are able to do it in Oct, then it would be done before the 2.6 release. That's meaningless for the docs of course, but has a symbolic meaning because we're doing so much for improving DX and docs for the 2.6 version.

Thanks!

[xabbuh]

see #4287 and fabpot/sphinx-php#20 for the support of Varnish configurations in our docs

[dbu]

@weaverryan i will try to work on this tomorrow. thanks to xabbuh we now can do tabs for varnish config... question: which branch should i work on? the 2.3 branch?

[xabbuh]

@dbu There's nothing specific for newer Symfony versions, right? So, 2.3 is the best I think.

[weaverryan]

I think with #4627 merged, we can close this :). @dbu if there is anything else that you still feel is missing/inaccurate (and which isn't in a pending PR of your own), let me know.

Thanks!