Merge branch '2.8'

* 2.8:
  Reset some more pygments styles
  Use pip instead of submodules
  Use numbered code block
  Add demo warning
  Move Sphinx files to _theme
  Update config
  Use a more recent version of Sphinx
  Temporary disable codeblock
  Use symfony.com theme on Platform.sh builds
  Update page_creation.rst
  [symfony#5593] Very little rewording and improving config
  Updated the profiler matchers article
  don't override existing variables
  [Cookbook][Session] fix default expiry field name
  Fix code

.gitignore

@@ -1,2 +1,3 @@
 /_build
 /_exts
+*.pyc

.travis.yml

@@ -9,7 +9,7 @@ cache:
         - $HOME/.cache/pip
         - _build
 
-install: pip install sphinx==1.1.3
+install: pip install sphinx~=1.3 git+https://github.com/fabpot/sphinx-php.git
 
 script: sphinx-build -nW -b html -d _build/doctrees . _build/html
 

_theme/_exts/symfonycom/sphinx/__init__.py

@@ -0,0 +1,167 @@
+from sphinx.highlighting import lexers, PygmentsBridge
+from pygments.style import Style
+from pygments.formatters import HtmlFormatter
+from pygments.token import Keyword, Name, Comment, String, Error, \
+     Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
+
+from sphinx.writers.html import HTMLTranslator
+from docutils import nodes
+from sphinx.locale import admonitionlabels, lazy_gettext
+
+customadmonitionlabels = admonitionlabels
+l_ = lazy_gettext
+customadmonitionlabels['best-practice'] = l_('Best Practice')
+
+def _getType(path):
+    return path[:path.find('/')]
+
+def _isIndex(path):
+    return 'index' in path
+
+class SensioHTMLTranslator(HTMLTranslator):
+    def __init__(self, builder, *args, **kwds):
+        HTMLTranslator.__init__(self, builder, *args, **kwds)
+        builder.templates.environment.filters['get_type'] = _getType
+        builder.templates.environment.tests['index'] = _isIndex
+        self.highlightlinenothreshold = 0
+
+    def visit_literal(self, node):
+        self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal'))
+        self.body.append('<code>')
+
+    def depart_literal(self, node):
+        self.body.append('</code>')
+        self.body.append('</tt>')
+
+    def visit_admonition(self, node, name=''):
+        self.body.append(self.starttag(node, 'div', CLASS=('admonition-wrapper')))
+        self.body.append('<div class="' + name + '"></div>')
+        self.body.append('<div class="admonition admonition-' + name + '">')
+        if name and name != 'seealso':
+            node.insert(0, nodes.title(name, customadmonitionlabels[name]))
+        self.set_first_last(node)
+
+    def depart_admonition(self, node=None):
+        self.body.append('</div></div>\n')
+
+    def visit_sidebar(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS=('admonition-wrapper')))
+        self.body.append('<div class="sidebar"></div>')
+        self.body.append('<div class="admonition admonition-sidebar">')
+        self.set_first_last(node)
+        self.in_sidebar = 1
+
+    def depart_sidebar(self, node):
+        self.body.append('</div></div>\n')
+        self.in_sidebar = None
+
+    # overriden to add a new highlight div around each block
+    def visit_literal_block(self, node):
+        if node.rawsource != node.astext():
+            # most probably a parsed-literal block -- don't highlight
+            return BaseTranslator.visit_literal_block(self, node)
+        lang = self.highlightlang
+        linenos = node.rawsource.count('\n') >= \
+                  self.highlightlinenothreshold - 1
+        highlight_args = node.get('highlight_args', {})
+        if node.has_key('language'):
+            # code-block directives
+            lang = node['language']
+            highlight_args['force'] = True
+        if node.has_key('linenos'):
+            linenos = node['linenos']
+        def warner(msg):
+            self.builder.warn(msg, (self.builder.current_docname, node.line))
+        highlighted = self.highlighter.highlight_block(
+            node.rawsource, lang, warn=warner, linenos=linenos,
+            **highlight_args)
+        starttag = self.starttag(node, 'div', suffix='',
+                                 CLASS='highlight-%s' % lang)
+        self.body.append('<div class="literal-block">' + starttag + highlighted + '</div></div>\n')
+        raise nodes.SkipNode
+
+class SensioStyle(Style):
+    background_color = "#000000"
+    default_style = ""
+
+    styles = {
+        # No corresponding class for the following:
+        #Text: "", # class: ''
+        Whitespace: "underline #f8f8f8", # class: 'w'
+        Error: "#a40000 border:#ef2929", # class: 'err'
+        Other: "#ffffff", # class 'x'
+
+    Comment: "italic #B729D9", # class: 'c'
+    Comment.Single: "italic #B729D9", # class: 'c1'
+    Comment.Multiline: "italic #B729D9", # class: 'cm'
+    Comment.Preproc: "noitalic #aaa", # class: 'cp'
+
+    Keyword: "#FF8400", # class: 'k'
+        Keyword.Constant: "#FF8400", # class: 'kc'
+        Keyword.Declaration: "#FF8400", # class: 'kd'
+        Keyword.Namespace: "#FF8400", # class: 'kn'
+        Keyword.Pseudo: "#FF8400", # class: 'kp'
+        Keyword.Reserved: "#FF8400", # class: 'kr'
+        Keyword.Type: "#FF8400", # class: 'kt'
+
+    Operator: "#E0882F", # class: 'o'
+    Operator.Word: "#E0882F", # class: 'ow' - like keywords
+
+    Punctuation: "#999999", # class: 'p'
+
+        # because special names such as Name.Class, Name.Function, etc.
+        # are not recognized as such later in the parsing, we choose them
+        # to look the same as ordinary variables.
+        Name: "#ffffff", # class: 'n'
+    Name.Attribute: "#ffffff", # class: 'na' - to be revised
+    Name.Builtin: "#ffffff", # class: 'nb'
+        Name.Builtin.Pseudo: "#3465a4", # class: 'bp'
+    Name.Class: "#ffffff", # class: 'nc' - to be revised
+        Name.Constant: "#ffffff", # class: 'no' - to be revised
+        Name.Decorator: "#888", # class: 'nd' - to be revised
+        Name.Entity: "#ce5c00", # class: 'ni'
+        Name.Exception: "#cc0000", # class: 'ne'
+    Name.Function: "#ffffff", # class: 'nf'
+        Name.Property: "#ffffff", # class: 'py'
+        Name.Label: "#f57900", # class: 'nl'
+        Name.Namespace: "#ffffff", # class: 'nn' - to be revised
+    Name.Other: "#ffffff", # class: 'nx'
+    Name.Tag: "#cccccc", # class: 'nt' - like a keyword
+    Name.Variable: "#ffffff", # class: 'nv' - to be revised
+        Name.Variable.Class: "#ffffff", # class: 'vc' - to be revised
+        Name.Variable.Global: "#ffffff", # class: 'vg' - to be revised
+        Name.Variable.Instance: "#ffffff", # class: 'vi' - to be revised
+
+    Number: "#1299DA", # class: 'm'
+
+        Literal: "#ffffff", # class: 'l'
+        Literal.Date: "#ffffff", # class: 'ld'
+
+        String: "#56DB3A", # class: 's'
+        String.Backtick: "#56DB3A", # class: 'sb'
+        String.Char: "#56DB3A", # class: 'sc'
+    String.Doc: "italic #B729D9", # class: 'sd' - like a comment
+        String.Double: "#56DB3A", # class: 's2'
+        String.Escape: "#56DB3A", # class: 'se'
+        String.Heredoc: "#56DB3A", # class: 'sh'
+        String.Interpol: "#56DB3A", # class: 'si'
+        String.Other: "#56DB3A", # class: 'sx'
+        String.Regex: "#56DB3A", # class: 'sr'
+    String.Single: "#56DB3A", # class: 's1'
+        String.Symbol: "#56DB3A", # class: 'ss'
+
+        Generic: "#ffffff", # class: 'g'
+        Generic.Deleted: "#a40000", # class: 'gd'
+        Generic.Emph: "italic #ffffff", # class: 'ge'
+        Generic.Error: "#ef2929", # class: 'gr'
+        Generic.Heading: "#000080", # class: 'gh'
+        Generic.Inserted: "#00A000", # class: 'gi'
+        Generic.Output: "#888", # class: 'go'
+        Generic.Prompt: "#745334", # class: 'gp'
+        Generic.Strong: "bold #ffffff", # class: 'gs'
+        Generic.Subheading: "bold #800080", # class: 'gu'
+        Generic.Traceback: "bold #a40000", # class: 'gt'
+    }
+
+def setup(app):
+    app.set_translator('html', SensioHTMLTranslator)

_theme/_templates/globaltoc.html

@@ -0,0 +1,20 @@
+<div class=submenu>
+    {% set menu = [ 
+        ('The Book', 'book/index'),
+        ('The Cookbook', 'cookbook/index'),
+        ('The Components', 'components/index'),
+        ('The Best Practices', 'best_practices/index'),
+        ('The Quick Tour', 'quick_tour/index'),
+        ('Reference', 'reference/index'),
+        ('Index', 'genindex'),
+        ('Contributing', 'contributing/index')
+    ] %}
+
+    <ul class="list_submenu list-unstyled">
+    {% for name, doc in menu %}
+        <li {% if loop.first %}class="first"{% endif %}>
+            <a href="{{ pathto(doc) }}">{{ name }}</a>
+        </li>
+    {% endfor %}
+    </ul>
+</div>

_theme/_templates/layout.html

@@ -0,0 +1,98 @@
+{% extends '!layout.html' %}
+
+{% set css_files = ['http://symfony.com/css/compiled/v5/all.css?v=4'] %}
+{# make sure the Sphinx stylesheet isn't loaded #}
+{% set style = '' %}
+{% set isIndex = pagename is index %}
+
+{% block extrahead %}
+{# add JS to support tabs #}
+<script src="http://symfony.com/js/v5/all.js?v=4"></script>
+
+{# pygment's styles are still loaded, undo some unwanted styles #}
+<style>
+.highlight .k, .highlight .gh, .highlight .gp,
+.highlight .gu, .highlight .kc, .highlight .kd,
+.highlight .kn, .highlight .kr, .highlight .nc,
+.highlight .nd, .highlight .ni, .highlight .nl,
+.highlight .nn, .highlight .nt, .highlight .ow,
+.highlight .se { font-weight: normal; }
+
+.highlight .c, .highlight .cm, .highlight .c1,
+.highlight .sd, .highlight .si { font-style: normal; }
+
+.doc { background: none; }
+#demo-warning {
+    border: 3px dashed #c00;
+    padding: 10px;
+    margin-bottom: 30px;
+}
+#demo-warning h4 { font-size: 1.7em;font-weight: bold; }
+#demo-warning p { margin-bottom: 0; }
+</style>
+{% endblock %}
+
+{% block header %}
+{# ugly way, now we have 2 body tags, but styles rely on these classes #}
+<body class="{{ pagename|get_type }} {% if isIndex %}doc_index{% else %}doc_article{% endif %} doc">
+{% endblock %}
+
+{% block content %}
+<div class="container"><div id="page-content">
+    <div class="row">
+        {%- if render_sidebar %}
+        <div id="sidebar" class="col-sm-3">
+            <div id="sidebar-content">
+                <div id="demo-warning">
+                    <h4>This is a demo</h4>
+                    <p>This is a demo provided by platform.sh.<br>
+                    <a href="http://symfony.com/doc/current/{{ pagename }}">Visit on symfony.com</a>.</p>
+                </div>
+
+                {%- include "globaltoc.html" %}
+
+                {% if not isIndex %}
+                    {%- include "localtoc.html" %}
+                {% endif %}
+            </div>
+        </div>
+        {%- endif %}
+
+        <div id="main" class="col-sm-9">
+            <ol class=breadcrumb>
+                <li><a href="#">Home</a></li>
+                <li><a href="#">Documentation</a></li>
+                {% for parent in parents %}
+                <li><a href="{{ parent.link|e }}">{{ parent.title }}</a></li>
+                {% endfor %}
+                <li class=active>{{ title }}</li>
+            </ol>
+
+            <h1 class="content_title">{{ title }}</h1>
+
+            <div class=page>
+            {% block body %}{% endblock %}
+            </div>
+
+            {% if prev and next %}
+            <div class=navigation>
+                <a href="{{ prev.link|e }}">« {{ prev.title|striptags|e }}</a>
+                <span class=separator>|</span>
+                <a href="{{ next.link|e }}">{{ next.title|striptags|e }} »</a>
+            </div>
+            {% endif %}
+
+            <div id="license">
+                <p>This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">License</a>.</p>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{# relbar1 is at the top and should not render the quick navigation #}
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+
+{# remove "generated by sphinx" footer #}
+{% block footer %}{% endblock %}

_theme/_templates/localtoc.html

@@ -0,0 +1,6 @@
+<div class="toc"> 
+    <h4>{{ _('Table Of Contents') }}</h4>
+    <div class=toc-content>
+        {{ toc }}
+    </div>
+</div>

book/page_creation.rst

@@ -104,7 +104,7 @@ Just add a second method to ``LuckyController``::
     // src/AppBundle/Controller/LuckyController.php
     // ...
 
-    class LuckyController
+    class LuckyController extends Controller
     {
         // ...
 
@@ -137,7 +137,7 @@ You can even shorten this with the handy :class:`Symfony\\Component\\HttpFoundat
     // --> don't forget this new use statement
     use Symfony\Component\HttpFoundation\JsonResponse;
 
-    class LuckyController
+    class LuckyController extends Controller
     {
         // ...
 
@@ -170,7 +170,7 @@ at the end:
         // src/AppBundle/Controller/LuckyController.php
         // ...
 
-        class LuckyController
+        class LuckyController extends Controller
         {
             /**
              * @Route("/lucky/number/{count}")
@@ -224,7 +224,7 @@ The best part is that you can access this value and use it in your controller::
     // src/AppBundle/Controller/LuckyController.php
     // ...
 
-    class LuckyController
+    class LuckyController extends Controller
     {
 
         /**

conf.py

@@ -16,9 +16,7 @@
 # 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('.'))
-
-sys.path.append(os.path.abspath('_exts'))
+sys.path.append(os.path.abspath('_theme/_exts'))
 
 # adding PhpLexer
 from sphinx.highlighting import lexers
@@ -34,11 +32,14 @@
 
 # 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.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
-    'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode', 'sensio.sphinx.bestpractice']
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+    'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode', 'sensio.sphinx.bestpractice', 'sensio.sphinx.codeblock',
+    'symfonycom.sphinx'
+]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['_theme/_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -74,7 +75,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# exclude_patterns = ['_build', 'bundles']
+exclude_patterns = ['_theme']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -126,7 +127,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'classic'
 
 # 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