Merge branch 'docs-fix'

docs/_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)

docs/_theme/_exts/symfonycom/sphinx/lexer.py

@@ -0,0 +1,23 @@
+from pygments.lexer import RegexLexer, bygroups, using
+from pygments.token import *
+from pygments.lexers.shell import BashLexer, BatchLexer
+
+class TerminalLexer(RegexLexer):
+    name = 'Terminal'
+    aliases = ['terminal']
+    filenames = []
+
+    tokens = {
+        'root': [
+            ('^\$', Generic.Prompt, 'bash-prompt'),
+            ('^[^\n>]+>', Generic.Prompt, 'dos-prompt'),
+            ('^#.+$', Comment.Single),
+            ('^.+$', Generic.Output),
+        ],
+        'bash-prompt': [
+            ('(.+)$', bygroups(using(BashLexer)), '#pop')
+        ],
+        'dos-prompt': [
+            ('(.+)$', bygroups(using(BatchLexer)), '#pop')
+        ],
+    }

docs/_theme/custom_rtd_theme/__init__.py

@@ -0,0 +1,19 @@
+"""Sphinx ReadTheDocs theme.
+
+From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
+
+"""
+from os import path
+
+__version__ = '0.4.2'
+__version_full__ = __version__
+
+
+def get_html_theme_path():
+    """Return list of HTML theme paths."""
+    cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
+    return cur_dir
+
+# See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
+def setup(app):
+    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

docs/_theme/custom_rtd_theme/breadcrumbs.html

@@ -0,0 +1,82 @@
+{# Support for Sphinx 1.3+ page_source_suffix, but don't break old builds. #}
+
+{% if page_source_suffix %}
+{% set suffix = page_source_suffix %}
+{% else %}
+{% set suffix = source_suffix %}
+{% endif %}
+
+{% if meta is defined and meta is not none %}
+{% set check_meta = True %}
+{% else %}
+{% set check_meta = False %}
+{% endif %}
+
+{% if check_meta and 'github_url' in meta %}
+{% set display_github = True %}
+{% endif %}
+
+{% if check_meta and 'bitbucket_url' in meta %}
+{% set display_bitbucket = True %}
+{% endif %}
+
+{% if check_meta and 'gitlab_url' in meta %}
+{% set display_gitlab = True %}
+{% endif %}
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+
+  <ul class="wy-breadcrumbs">
+    {% block breadcrumbs %}
+      <li><a href="{{ pathto(master_doc) }}">{{ _('Docs') }}</a> &raquo;</li>
+        {% for doc in parents %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+        {% endfor %}
+      <li>{{ title }}</li>
+    {% endblock %}
+    {% block breadcrumbs_aside %}
+      <li class="wy-breadcrumbs-aside">
+        {% if hasdoc(pagename) %}
+            {% if display_github %}
+            {% if check_meta and 'github_url' in meta %}
+              <!-- User defined GitHub URL -->
+              <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% else %}
+              <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% endif %}
+          {% elif display_bitbucket %}
+            {% if check_meta and 'bitbucket_url' in meta %}
+              <!-- User defined Bitbucket URL -->
+              <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% else %}
+              <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode|default("view") }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% endif %}
+          {% elif display_gitlab %}
+            {% if check_meta and 'gitlab_url' in meta %}
+              <!-- User defined GitLab URL -->
+              <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% else %}
+              <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% endif %}
+          {% elif show_source and source_url_prefix %}
+            <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
+          {% elif show_source and has_source and sourcename %}
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+          {% endif %}
+        {% endif %}
+      </li>
+    {% endblock %}
+  </ul>
+
+  {% if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="breadcrumb navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+      {% endif %}
+  </div>
+  {% endif %}
+  <hr/>
+</div>

docs/_theme/custom_rtd_theme/footer.html

@@ -0,0 +1,52 @@
+<footer>
+  {% if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n" rel="next">{{ _('Next') }} <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> {{ _('Previous') }}</a>
+      {% endif %}
+    </div>
+  {% endif %}
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}{% endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}{% endtrans %}
+      {%- endif %}
+    {%- endif %}
+
+    {%- if build_id and build_url %}
+      {% trans build_url=build_url, build_id=build_id %}
+        <span class="build">
+          Build
+          <a href="{{ build_url }}">{{ build_id }}</a>.
+        </span>
+      {% endtrans %}
+    {%- elif commit %}
+      {% trans commit=commit %}
+        <span class="commit">
+          Revision <code>{{ commit }}</code>.
+        </span>
+      {% endtrans %}
+    {%- elif last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+
+    </p>
+  </div>
+
+  {%- if show_sphinx %}
+  {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}.
+  {%- endif %}
+
+  {%- block extrafooter %} {% endblock %}
+
+</footer>
+