Use PHPDoc for Task & Transformer Reference

.gitignore

@@ -1,6 +1,8 @@
 /composer.lock
+/var
 /vendor
 /vendor-sf3
 /vendor-sf4
 /vendor-sf5
-.env
+/.env
+/.phpdoc/cache

.phpdoc/template/base.html.twig

@@ -0,0 +1,8 @@
+{% extends 'layout.html.twig' %}
+
+{% block javascripts %}
+    {{ parent() }}
+    <script>
+        {% include 'js/prism.js' %}
+    </script>
+{% endblock %}

.phpdoc/template/components/process_bundle_interfaces.html.twig

@@ -0,0 +1,17 @@
+{% set interfaces_str =  include("components/recursive_iterfaces.html.twig", {'class': class}) %}
+
+{% if "IterableTaskInterface" in interfaces_str %}
+    iterable
+{% endif %}
+
+{% if "FlushableTaskInterface" in interfaces_str %}
+    flushable
+{% endif %}
+
+{% if "BlockingTaskInterface" in interfaces_str %}
+    blocking
+{% endif %}
+
+{% if "TaskInterface" in interfaces_str %}
+    task
+{% endif %}

.phpdoc/template/components/recursive_iterfaces.html.twig

@@ -0,0 +1,22 @@
+{% if class is defined and class %}
+    {% for interface in class.interfaces %}
+        {{ interface.name }}
+        {% if interface.parent|length > 0 %}
+            {% for parent_interface in interface.parent %}
+                {% include "components/recursive_iterfaces.html.twig" with {'interface': parent_interface, 'class': false, 'known_interfaces': known_interfaces} %}
+            {% endfor %}
+        {% endif %}
+    {% endfor %}
+
+    {% if class.parent %}
+        {% include "components/recursive_iterfaces.html.twig" with {'class': class.parent, 'known_interfaces': known_interfaces} %}
+    {% endif %}
+{% endif %}
+
+
+{% if interface is defined %}
+    {{ interface.name }}
+    {% for parent_interface in interface.parent %}
+        {% include "components/recursive_iterfaces.html.twig" with {'interface': parent_interface, 'known_interfaces': known_interfaces} %}
+    {% endfor %}
+{% endif %}

.phpdoc/template/components/recursive_namespace_tree.html.twig

@@ -0,0 +1,32 @@
+{% if namespace.children|length > 0 or namespace.interfaces|length > 0 or namespace.classes|length > 0 or namespace.traits|length > 0 %}
+    <ul class="phpdocumentor-list">
+        {% for child in namespace.children %}
+            {% if child.children|length > 0 or child.interfaces|length > 0 or child.classes|length > 0 or child.traits|length > 0 %}
+                <li>
+                    {{ child|route('class:short') }}
+                    {% include 'components/recursive_namespace_tree.html.twig' with {'namespace': child} %}
+                </li>
+            {% endif %}
+        {% endfor %}
+
+        {% for interface in namespace.interfaces %}
+            <li class="sidebar-item -interface">{{ interface|route('class:short') }}</li>
+        {% endfor %}
+
+        {% for trait in namespace.traits %}
+            <li class="sidebar-item -trait">{{ trait|route('class:short') }}</li>
+        {% endfor %}
+
+        {% for class in namespace.classes %}
+            {% if class.abstract %}
+                <li class="sidebar-item -class -abstract">{{ class|route('class:short') }}</li>
+            {% endif %}
+        {% endfor %}
+
+        {% for class in namespace.classes %}
+            {% if not class.abstract %}
+                <li class="sidebar-item -class">{{ class|route('class:short') }}</li>
+            {% endif %}
+        {% endfor %}
+    </ul>
+{% endif %}

.phpdoc/template/components/sidebar.html.twig

@@ -0,0 +1,68 @@
+<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button"/>
+<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
+    Menu
+</label>
+<aside class="phpdocumentor-column -four phpdocumentor-sidebar">
+    {% set menu = menu() %}
+    {% if menu %}
+        <section class="phpdocumentor-sidebar__category">
+            <h2 class="phpdocumentor-sidebar__category-header"><a href="{{ menu.path }}">{{ menu.label }}</a></h2>
+            {% for menuItem in menu.items %}
+                {{ include('menu.html.twig', {menuItem: menuItem}, with_context = false) }}
+            {% endfor %}
+        </section>
+    {% endif %}
+
+    <section class="phpdocumentor-sidebar__category">
+        <h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
+        {% if usesNamespaces or not usesPackages %}
+            {% if project.namespace.functions is not empty or project.namespace.constants is not empty or project.namespace.classes is not empty or project.namespace.interfaces is not empty or project.namespace.traits is not empty %}
+                <h3 class="phpdocumentor-sidebar__root-namespace">{{ project.namespace|route('Global') }}</h3>
+            {% endif %}
+            {% for namespace in project.namespace.children %}
+                {# Override to put the 2 first items on the same level #}
+                {% for child1 in namespace.children %}
+                    {% for child2 in child1.children %}
+                        <h4 class="phpdocumentor-sidebar__root-namespace">
+                            {{ namespace|route('class:short') }}
+                            / {{ child1|route('class:short') }}
+                            / {{ child2|route('class:short') }}
+                        </h4>
+                        {% include 'components/recursive_namespace_tree.html.twig' with {'namespace': child2} %}
+                    {% endfor %}
+                {% endfor %}
+            {% endfor %}
+        {% endif %}
+    </section>
+
+    {% if usesPackages %}
+        <section class="phpdocumentor-sidebar__category">
+            <h2 class="phpdocumentor-sidebar__category-header">Packages</h2>
+            {% for package in project.package.children %}
+                <h3 class="phpdocumentor-sidebar__root-package">{{ package|route('class:short') }}</h3>
+                {% if package.children is not empty %}
+                    <ul class="phpdocumentor-list">
+                        {% for child in package.children %}
+                            <li>{{ child|route('class:short') }}</li>
+                        {% endfor %}
+                    </ul>
+                {% endif %}
+            {% endfor %}
+        </section>
+    {% endif %}
+
+    <section class="phpdocumentor-sidebar__category">
+        <h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
+        {% if project.settings.custom['graphs.enabled'] %}
+            <h3 class="phpdocumentor-sidebar__root-package"><a href="graphs/classes.html">Class Diagram</a></h3>
+        {% endif %}
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
+    </section>
+
+    <section class="phpdocumentor-sidebar__category">
+        <h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
+    </section>
+</aside>

.phpdoc/template/components/table-of-contents.html.twig

@@ -0,0 +1,81 @@
+{% if packages|default([]) is not empty %}
+    <h3 id="packages">
+        Packages
+        <a href="#packages" class="headerlink"><i class="fas fa-link"></i></a>
+    </h3>
+
+    <dl class="phpdocumentor-table-of-contents">
+        {% for package in packages %}
+            <dt class="phpdocumentor-table-of-contents__entry -package">{{ package|route('class:short') }}</dt>
+        {% endfor %}
+    </dl>
+{% endif %}
+
+{% if namespaces|default([]) is not empty %}
+    <h3 id="namespaces">
+        Namespaces
+        <a href="#namespaces" class="headerlink"><i class="fas fa-link"></i></a>
+    </h3>
+
+    <dl class="phpdocumentor-table-of-contents">
+        {% for namespace in namespaces %}
+            <dt class="phpdocumentor-table-of-contents__entry -namespace">{{ namespace|route('class:short') }}</dt>
+        {% endfor %}
+    </dl>
+{% endif %}
+
+{% if node.interfaces is not empty or node.classes is not empty or node.traits is not empty %}
+    <h3 id="interfaces_class_traits">
+        Interfaces, Classes and Traits
+        <a href="#interfaces_class_traits" class="headerlink"><i class="fas fa-link"></i></a>
+    </h3>
+
+    <dl class="phpdocumentor-table-of-contents">
+        {% for interface in node.interfaces %}
+            <dt class="phpdocumentor-table-of-contents__entry -interface">{{ interface|route('class:short') }}</dt>
+            <dd>{{ interface.summary }}</dd>
+        {% endfor %}
+
+        {% for class in node.classes %}
+            <dt class="phpdocumentor-table-of-contents__entry -class {{ class.abstract ? '-abstract' : '' }}">
+                {{ class|route('class:short') }}
+                {% set task_interfaces_str = include("components/process_bundle_interfaces.html.twig", {'class': class})|spaceless|capitalize %}
+                {% if task_interfaces_str|length > 0 %}
+                    <span class="processbundle-task-interfaces">({{ task_interfaces_str }})</span>
+                {% endif %}
+            </dt>
+            <dd>{{ class.summary }}</dd>
+        {% endfor %}
+
+        {% for trait in node.traits %}
+            <dt class="phpdocumentor-table-of-contents__entry -trait">{{ trait|route('class:short') }}</dt>
+            <dd>{{ trait.summary }}</dd>
+        {% endfor %}
+    </dl>
+{% endif %}
+
+{% set constants = constants(node) %}
+{% set properties = properties(node) %}
+{% set methods = methods(node) %}
+
+{% if constants is not empty or node.functions is not empty or methods is not empty or properties is not empty %}
+    <h3 id="toc">
+        Table of Contents
+        <a href="#toc" class="headerlink"><i class="fas fa-link"></i></a>
+    </h3>
+
+    <dl class="phpdocumentor-table-of-contents">
+        {% for constant in constants(node)|sortByVisibility %}
+            {{ include('components/table-of-contents-entry.html.twig', {'type': 'constant', 'node': constant}) }}
+        {% endfor %}
+        {% for property in properties(node)|sortByVisibility %}
+            {{ include('components/table-of-contents-entry.html.twig', {'type': 'property', 'node': property}) }}
+        {% endfor %}
+        {% for method in methods(node)|sortByVisibility %}
+            {{ include('components/table-of-contents-entry.html.twig', {'type': 'method', 'node': method}) }}
+        {% endfor %}
+        {% for function in node.functions|default([]) %}
+            {{ include('components/table-of-contents-entry.html.twig', {'type': 'function', 'node': function}) }}
+        {% endfor %}
+    </dl>
+{% endif %}

.phpdoc/template/components/tags.html.twig

@@ -0,0 +1,60 @@
+{#
+ # Override to add @example features
+ # @see https://github.com/phpDocumentor/phpDocumentor/blob/master/data/templates/default/components/tags.html.twig
+ #}
+{% set tags = node.tags|filter((v,k) => k not in ['var', 'param', 'property', 'property-read', 'property-write', 'method', 'return', 'package', 'api', 'example']) %}
+
+{% for tagName,tags in node.tags if tagName in ['example'] %}
+    {% if loop.first %}
+        <h5 class="phpdocumentor-tag-list__heading" id="examples">
+            Examples
+            <a href="#examples" class="headerlink"><i class="fas fa-link"></i></a>
+        </h5>
+    {% endif %}
+    <dl class="phpdocumentor-tag-list">
+        {% for tag in tags %}
+            <dt class="phpdocumentor-tag-list__entry">
+                <span class="phpdocumentor-tag__name">{{ tag.description | description | markdown }}</span>
+            </dt>
+            <dd class="phpdocumentor-tag-list__definition">
+                {% if tag.example %}
+                    <pre class="pre-scrollable"><code class="language-{{ tag.filePath|split('.')|last }}">{{ tag.example|escape }}</code></pre>
+                {% endif %}
+            </dd>
+    {% endfor %}
+    </dl>
+{% endfor %}
+
+{% if tags|length > 0 %}
+    <h5 class="phpdocumentor-tag-list__heading" id="tags">
+        Tags
+        <a href="#tags" class="headerlink"><i class="fas fa-link"></i></a>
+    </h5>
+    <dl class="phpdocumentor-tag-list">
+        {% for name,seriesOfTag in tags %}
+            {% for tag in seriesOfTag %}
+                <dt class="phpdocumentor-tag-list__entry">
+                    <span class="phpdocumentor-tag__name">{{ name }}</span>
+                </dt>
+                <dd class="phpdocumentor-tag-list__definition">
+                    {% if tag.version %}
+                        <span class="phpdocumentor-tag-link">{{ tag.version }}</span>
+                    {% endif %}
+                    {% if tag.type %}
+                        <span class="phpdocumentor-tag-link">{{ tag.type|route('class:short')|join('|')|raw }}</span>
+                    {% endif %}
+                    {% if tag.reference %}
+                        <span class="phpdocumentor-tag-link">{{ tag.reference|route('class:short')|join('|')|raw }}</span>
+                    {% endif %}
+                    {% if tag.link %}
+                        <a class="phpdocumentor-tag-link" href="{{ tag.link }}">{% if tag.description is not empty %} {{ tag.description | description | markdown }} {% else %} {{ tag.link }} {%  endif %}</a>
+                    {% endif %}
+
+                    {% if not tag.link %}
+                        {{ include('components/description.html.twig', {'node': tag}) }}
+                    {% endif %}
+                </dd>
+            {% endfor %}
+        {% endfor %}
+    </dl>
+{% endif %}

.phpdoc/template/css/custom.css.twig

@@ -0,0 +1,66 @@
+{% include 'css/prism.css' %}
+
+/* Sidebar improvements */
+.sidebar-item:before {
+    content: '';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/method.svg.twig')|trim|raw }}') no-repeat center center;
+    width: 1.25rem;
+    height: 1.25rem;
+    line-height: 1.25rem;
+    border-radius: 50%;
+    font-weight: 600;
+    color: white;
+    text-align: center;
+    font-size: .75rem;
+    margin-top: .2rem;
+    margin-right: .3rem;
+    display: inline-block;
+}
+
+.sidebar-item.-interface:before {
+    content: 'I';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/interface.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.sidebar-item.-class:before {
+    content: 'C';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/class.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.sidebar-item.-class.-abstract:before {
+    content: 'A';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/abstract.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.sidebar-item.-trait:before {
+    content: 'T';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/trait.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.phpdocumentor .phpdocumentor-sidebar .phpdocumentor-list .phpdocumentor-list {
+    padding-top: 0;
+    padding-left: 0;
+}
+
+.processbundle-task-interfaces {
+    padding-left: 1rem;
+    color: #aaaaaa;
+}
+
+/* Overrides */
+.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-interface:before {
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/interface.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-class:before {
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/class.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-class.-abstract:before {
+    content: 'A';
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/abstract.svg.twig')|trim|raw }}') no-repeat center center;
+}
+
+.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-trait:before {
+    background: transparent url('data:image/svg+xml;utf8,{{ include('icons/trait.svg.twig')|trim|raw }}') no-repeat center center;
+}