Merge pull request #93 from vitorbrandao/GH-78-readthedocs-fix

GH-78 Add extra docs extensions

Makefile

@@ -180,13 +180,18 @@ php-cs-fixer-apply: ##  Run the PHP Coding Standards Fixer (PHP CS Fixer)
 
 ### Composer ###
 composer-sf4-lowest: ## Install composer dependencies using sf4 --prefer-lowest
-	SYMFONY_REQUIRE=4.4 composer update --prefer-dist --verbose --prefer-lowest
+	SYMFONY_REQUIRE=4.4 composer update --prefer-dist --prefer-lowest
 .PHONY: composer-sf3
 
 composer-sf4: ## Install composer dependencies using sf4
-	SYMFONY_REQUIRE=4.4 composer update --prefer-dist --verbose
+	SYMFONY_REQUIRE=4.4 composer update --prefer-dist
 .PHONY: composer-sf4
 
 composer-sf5: ## Install composer dependencies using sf5
-	SYMFONY_REQUIRE=5.3 composer update --prefer-dist --verbose
+	SYMFONY_REQUIRE=5.3 composer update --prefer-dist
 .PHONY: composer-sf5
+
+### PHPUnit tests ###
+phpunit: ## Run PHPUnit tests
+	XDEBUG_MODE=coverage phpunit --coverage-text
+.PHONY: phpunit

docs/_exts/sensio/sphinx/__init__.py

@@ -0,0 +1,170 @@
+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')
+
+
+class SensioHTMLTranslator(HTMLTranslator):
+    def __init__(self, builder, *args, **kwds):
+        HTMLTranslator.__init__(self, builder, *args, **kwds)
+        self.highlightlinenothreshold = 5
+
+    def visit_literal(self, node):
+        self.body.append('<code class="notranslate">')
+
+    def depart_literal(self, node):
+        self.body.append('</code>')
+
+    def visit_image(self, node):
+        self.body.append(
+            self.starttag(node,
+                          'div',
+                          '',
+                          CLASS='figure %s' % ' '.join(node['classes'])))
+        HTMLTranslator.visit_image(self, node)
+
+    def depart_image(self, node):
+        HTMLTranslator.depart_image(self, node)
+        self.body.append('</div>')
+
+    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
+        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']
+        else:
+            linenos = node.rawsource.count('\n') >= \
+                  self.highlightlinenothreshold - 1
+
+        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 notranslate">' + 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'
+    }

docs/_exts/sensio/sphinx/bestpractice.py

@@ -0,0 +1,29 @@
+from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.locale import _
+
+
+class bestpractice(nodes.Admonition, nodes.Element): pass
+
+
+class BestPractice(BaseAdmonition):
+
+    node_class = bestpractice
+
+
+def visit_bestpractice_node(self, node):
+    self.visit_admonition(node, 'best-practice')
+
+
+def depart_bestpractice_node(self, node):
+    self.depart_admonition(node)
+
+
+def setup(app):
+    app.add_node(bestpractice,
+                 html=(visit_bestpractice_node, depart_bestpractice_node))
+    app.add_directive('best-practice', BestPractice)
+
+    return {'parallel_read_safe': True}

docs/_exts/sensio/sphinx/codeblock.py

@@ -0,0 +1,90 @@
+"""
+    :copyright: (c) 2010-2015 Fabien Potencier
+    :license: MIT, see LICENSE for more details.
+"""
+
+from sphinx.directives.code import CodeBlock
+from docutils.parsers.rst import directives
+from docutils import nodes
+try:
+    from html import escape
+except ImportError:
+    # old python 2
+    from cgi import escape
+
+"""
+A wrapper around the built-in CodeBlock class to always
+enable line numbers.
+and add support for zerocopy
+"""
+class NumberedCodeBlock(CodeBlock):
+    option_spec = {
+        'linenos': directives.flag,
+        'zerocopy': directives.flag,
+        'dedent': int,
+        'lineno-start': int,
+        'emphasize-lines': directives.unchanged_required,
+        'caption': directives.unchanged_required,
+        'class': directives.class_option,
+        'name': directives.unchanged,
+    }
+
+    def run(self):
+        self.options['linenos'] = True
+        literal = super(NumberedCodeBlock, self).run()[0];
+
+        if 'zerocopy' in self.options:
+            resultnode = codeblock()
+            resultnode['code'] = u'\n'.join(self.content)
+            resultnode['zerocopy'] = 'zerocopy'
+            resultnode.append(literal)
+
+            return [resultnode]
+        else:
+            return [literal]
+
+class codeblock(nodes.General, nodes.Element):
+    pass
+
+
+def visit_codeblock_html(self, node):
+    if 'zerocopy' in node:
+        self.body.append(
+            self.starttag(node, 'div', CLASS='zeroclipboard-pre input-group'))
+
+
+def depart_codeblock_html(self, node):
+    if 'zerocopy' in node:
+        self.body.append('''
+    <span class="input-group-btn zeroclipboard-group-btn">
+        <button data-clipboard-text="%s" class="zeroclipboard btn" type="button">
+           <svg viewBox="0 0 20 20" version="1.1" xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" xml:space="preserve">
+           <path d="M17,14.7c0,0.6-0.4,1-1,1H8.9c-0.6,0-1-0.4-1-1c0-0.6,0.4-1,1-1H16C16.6,13.7,17,14.2,17,14.7z M16,10.2H8.9
+               c-0.6,0-1,0.4-1,1c0,0.6,0.4,1,1,1H16c0.6,0,1-0.4,1-1C17,10.6,16.6,10.2,16,10.2z M16,6.6H8.9c-0.6,0-1,0.4-1,1s0.4,1,1,1H16
+               c0.6,0,1-0.4,1-1S16.6,6.6,16,6.6z M20.6,5.7v10.2c0,2.2-1.8,4.1-4.1,4.1H8.4C7,20,5.7,19.3,5,18.2c-0.2,0.1-0.4,0.2-0.6,0.2
+               c-2.2,0-4.1-1.8-4.1-4.1V4.1C0.4,1.8,2.2,0,4.4,0h8.2c0.6,0,1,0.4,1,1c0,0.2-0.1,0.4-0.2,0.6h3.1C18.8,1.6,20.6,3.4,20.6,5.7z
+                M6.6,2H4.4C3.3,2,2.4,3,2.4,4.1v10.2c0,1.1,0.9,2,2,2.1c0-0.2,0-0.3,0-0.5V5.7C4.3,4.1,5.3,2.7,6.6,2z M18.6,5.7
+               c0-1.1-0.9-2.1-2.1-2.1H8.4c-1.1,0-2.1,0.9-2.1,2.1v10.2C6.3,17,7.2,18,8.4,18h8.2c1.1,0,2.1-0.9,2.1-2.1V5.7z"/>
+           </svg>
+        </button>
+    </span>
+</div>
+        ''' % escape(node['code']))
+
+
+def visit_codeblock_latex(self, node):
+    pass
+
+
+def depart_codeblock_latex(self, node):
+    pass
+
+
+def setup(app):
+    app.add_node(codeblock,
+                 html=(visit_codeblock_html, depart_codeblock_html),
+                 latex=(visit_codeblock_latex, depart_codeblock_latex))
+    app.add_directive('code-block', NumberedCodeBlock, override = True)
+    app.add_directive('sourcecode', NumberedCodeBlock, override = True)
+
+    return {'parallel_read_safe': True}

docs/_exts/sensio/sphinx/lexer.py

@@ -0,0 +1,20 @@
+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')],
+    }

src/Extension/Plugin/AbstractPlugin.php

@@ -73,7 +73,7 @@ abstract class AbstractPlugin implements PluginInterface
      * @param ExtensionInterface $extension A ExtensionInterface instance
      * @param string             $method    Method name
      */
-    public function __construct($name, ExtensionInterface $extension, $method)
+    public function __construct(string $name, ExtensionInterface $extension, string $method)
     {
         $this->name = $name;
         $this->extension = $extension;

tests/Sandbox/App/.env

@@ -0,0 +1,19 @@
+# In all environments, the following files are loaded if they exist,
+# the latter taking precedence over the former:
+#
+#  * .env                contains default values for the environment variables needed by the app
+#  * .env.local          uncommitted file with local overrides
+#  * .env.$APP_ENV       committed environment-specific defaults
+#  * .env.$APP_ENV.local uncommitted environment-specific overrides
+#
+# Real environment variables win over .env files.
+#
+# DO NOT DEFINE PRODUCTION SECRETS IN THIS FILE NOR IN ANY OTHER COMMITTED FILES.
+#
+# Run "composer dump-env prod" to compile .env files for production use (requires symfony/flex >=1.2).
+# https://symfony.com/doc/current/best_practices.html#use-environment-variables-for-infrastructure-configuration
+
+###> symfony/framework-bundle ###
+APP_ENV=dev
+APP_SECRET=01d4ed2151d5e01fbdf3095c246cf7d3
+###< symfony/framework-bundle ###