Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

.gitignore

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

.gitmodules

@@ -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
 

.travis.yml

@@ -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)

_exts

@@ -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/_exts/symfonycom/__init__.py

@@ -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>Pull request build</h4>
+                    <p>Each pull request of the Symfony Documentation is automatically deployed and hosted on <a href="https://platform.sh">Platform.sh</a>.<br>
+                    View this page on <a href="https://symfony.com/doc/current/{{ pagename }}">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/_exts/symfonycom/sphinx/__init__.py

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

_theme/_templates/globaltoc.html

@@ -333,7 +333,7 @@ were defined by the PHP community. You can learn more about
 use the `PHP-CS-Fixer`_, which is a command-line utility that can fix the
 coding standards of an entire codebase in a matter of seconds.
 
-.. _`full definition`: http://en.wikipedia.org/wiki/Business_logic
+.. _`full definition`: https://en.wikipedia.org/wiki/Business_logic
 .. _`Doctrine project`: http://www.doctrine-project.org/
 .. _`fixture class`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
 .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/

_theme/_templates/layout.html

@@ -180,5 +180,5 @@ that you store them outside the Symfony project and make them available
 through environment variables. Learn how to do it in the following article:
 :doc:`/cookbook/configuration/external_parameters`
 
-.. _`feature toggles`: http://en.wikipedia.org/wiki/Feature_toggle
+.. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
 .. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html

_theme/_templates/localtoc.html

@@ -177,4 +177,4 @@ the Symfony directory structure.
 .. _`Get Started`: https://getcomposer.org/doc/00-intro.md
 .. _`Composer download page`: https://getcomposer.org/download/
 .. _`public checksums repository`: https://github.com/sensiolabs/checksums
-.. _`these steps`: http://fabien.potencier.org/article/73/signing-project-releases
+.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html

best_practices/business-logic.rst

@@ -85,7 +85,7 @@ makes them easier to re-use later.
 
     Add buttons in the templates, not in the form classes or the controllers.
 
-Since Symfony 2.5, you can add buttons as fields on your form. This is a nice
+Since Symfony 2.3, you can add buttons as fields on your form. This is a nice
 way to simplify the template that renders your form. But if you add the buttons
 directly in your form class, this would effectively limit the scope of that form:
 

best_practices/configuration.rst

@@ -121,4 +121,4 @@ for your test fixtures.
 .. _`PhpUnit`: https://phpunit.de/
 .. _`PhpSpec`: http://www.phpspec.net/
 .. _`Mink`: http://mink.behat.org
-.. _`smoke testing`: http://en.wikipedia.org/wiki/Smoke_testing_(software)
+.. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)

best_practices/creating-the-project.rst

@@ -30,7 +30,7 @@ much more concise:
 
     Keep in mind that ``web/`` is a public directory and that anything stored
     here will be publicly accessible, including all the original asset files
-    (e.g. Sass, LESS and CoffeScript files).
+    (e.g. Sass, LESS and CoffeeScript files).
 
 Using Assetic
 -------------

best_practices/forms.rst

@@ -619,8 +619,8 @@ session.
 Flash Messages
 ~~~~~~~~~~~~~~
 
-You can also store small messages that will be stored on the user's session
-for exactly one additional request. This is useful when processing a form:
+You can also store small messages that will be stored on the user's session.
+This is useful when processing a form:
 you want to redirect and have a special message shown on the *next* page.
 These types of messages are called "flash" messages.
 
@@ -675,9 +675,17 @@ the ``notice`` message:
             </div>
         <?php endforeach ?>
 
-By design, flash messages are meant to live for exactly one request (they're
-"gone in a flash"). They're designed to be used across redirects exactly as
-you've done in this example.
+.. note::
+
+    By design, flash messages are meant to be processed exactly once. This means
+    that they vanish from the session automatically when they are retrieved from
+    the flash bag by calling the ``get()`` method.
+
+.. tip::
+
+    You can use the
+    :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek`
+    method instead to retrieve the message while keeping it in the bag.
 
 .. index::
    single: Controller; Response object