docs: WiP - phpdocumentor templates

This is mainly to not lose what I have so far. The idea is to run
phpdocumentor on a select number of source code files, with the goal
of rendering something like https://www.adminer.org/en/extension/

The output should be in Markdown, ideally injected into a file in the
docs/ folder, and auto-deployed to the docs website.

docs/phpdoc-template/class.md.twig

@@ -0,0 +1,31 @@
+## {{ class.name }}
+
+{{ class.summary|raw }}
+
+{{ class.description|raw }}
+
+* Full name: {{ class.FullyQualifiedStructuralElementName }}
+{% if class.parent %}* Parent class: {{ class.parent.FullyQualifiedStructuralElementName }}
+{% endif %}
+{% if class.interfaces is not empty %}* This class implements: {{ class.interfaces|join(', ')|raw }}
+{% endif %}
+{% if class.deprecated %}* **Warning:** this class is **deprecated**. This means that this class will likely be removed in a future version.
+{% endif %}
+
+{% if class.tags.see is not empty or class.tags.link is not empty %}
+**See Also:**
+
+{% for see in class.tags.see %}
+* {{ see.reference }} {% if see.description %}- {{ see.description|raw }}{% endif %}
+{% endfor %}
+{% for link in class.tags.link %}
+* {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description|raw }}{% endif %}
+{% endfor %}
+
+{% endif %}{# class.tags.see || class.tags.link #}
+
+{% for method in class.methods %}
+{% if method.visibility == 'public' %}
+{% include 'method.md.twig' %}
+{% endif %}
+{% endfor %}

docs/phpdoc-template/index.md.twig

@@ -0,0 +1,9 @@
+# {{ project.name|raw }}
+
+{% include 'toc.md.twig' %}
+
+{% for class in project.indexes.classes|sort_asc %}
+{% if not class.abstract %}
+{% include 'class.md.twig' %}
+{% endif %}
+{% endfor %}

docs/phpdoc-template/method.md.twig

@@ -0,0 +1,52 @@
+### {{ class.name }}::{{ method.name }}
+
+{{ method.summary|raw }}
+
+{# Method signature #}
+```php
+{{ class.name }}::{{ method.name }}( {% for argument in method.arguments %}
+{{- argument.types ? argument.types|join('|')~' ' }}
+{{- argument.byReference ? '&' }}
+{{- argument.name }}{{ argument.default ? (' = '~argument.default)|raw }}
+{%- if not loop.last %}, {% endif %}
+{%- endfor %} )
+{{- method.response.types ? ': '~method.response.types|join('|') }}
+```
+
+{{ method.description|raw }}
+
+{% if method.static %}* This method is **static**.{% endif %}
+{% if method.deprecated %}* **Warning:** this method is **deprecated**. This means that this method will likely be removed in a future version.
+{% endif %}
+
+{% if method.arguments is not empty %}
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+{% for argument in method.arguments %}
+| `{{ argument.name }}` | **{{ argument.types ? argument.types|join('\\|')|raw|replace({'|': '\\|'}) }}** | {{ argument.description|raw|replace({'|': '\\|'}) }} |
+{% endfor %}
+
+{% endif %}{# method.arguments is not empty #}
+
+{% if method.response.description %}
+**Return Value:**
+
+{{ method.response.description|raw }}
+
+{% endif %}
+
+{% if method.tags.see is not empty or method.tags.link is not empty %}
+**See Also:**
+
+{% for see in method.tags.see %}
+* {{ see.reference }} {% if see.description %}- {{ see.description|raw }}{% endif %}
+{% endfor %}
+{% for link in method.tags.link %}
+* {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description|raw }}{% endif %}
+{% endfor %}
+
+{% endif %}{# method.tags.see || method.tags.link #}
+
+---

docs/phpdoc-template/template.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<template>
+  <version>0.3.1</version>
+  <description>Generate usage documentation (documents only it's public API) for a small library in Markdown format so it can be published in GitHub.</description>
+  <transformations>
+    <transformation writer="twig" source="templates/public-onefile/index.md.twig" artifact="README.md" />
+  </transformations>
+  <parameters>
+    <parameter key="twig-debug">true</parameter>
+  </parameters>
+</template>

docs/phpdoc-template/toc.md.twig

@@ -0,0 +1,14 @@
+## Table of Contents
+
+| Method | Description |
+|--------|-------------|
+{% for class in project.indexes.classes|sort_asc %}
+{% if not class.abstract %}
+| [**{{ class.name }}**](#{{ class.name }}) | {{ class.summary|raw|replace({'\n': '', '\r': '', '|': '\\|'}) }} |
+{% for method in class.methods %}
+{% if method.visibility == 'public' %}
+| [{{ class.name }}::{{ method.name }}](#{{ class.name }}{{ method.name }}) | {{ method.summary|raw|replace({'\n': '', '\r': '', '|': '\\|'}) }} {{ method.line }} {{ dump(method.getPath) }}  |
+{% endif %}
+{% endfor %}
+{% endif %}
+{% endfor %}