From 762a8948b9788a3022719f13449e1804cc722ba2 Mon Sep 17 00:00:00 2001
From: Gerry Demaret <gerry@x-net.be>
Date: Mon, 14 Aug 2023 14:42:09 +0200
Subject: [PATCH] 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  | 31 +++++++++++++++++
 docs/phpdoc-template/index.md.twig  |  9 +++++
 docs/phpdoc-template/method.md.twig | 52 +++++++++++++++++++++++++++++
 docs/phpdoc-template/template.xml   | 11 ++++++
 docs/phpdoc-template/toc.md.twig    | 14 ++++++++
 5 files changed, 117 insertions(+)
 create mode 100644 docs/phpdoc-template/class.md.twig
 create mode 100644 docs/phpdoc-template/index.md.twig
 create mode 100644 docs/phpdoc-template/method.md.twig
 create mode 100644 docs/phpdoc-template/template.xml
 create mode 100644 docs/phpdoc-template/toc.md.twig

diff --git a/docs/phpdoc-template/class.md.twig b/docs/phpdoc-template/class.md.twig
new file mode 100644
index 00000000..7e032d7a
--- /dev/null
+++ b/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 %}
diff --git a/docs/phpdoc-template/index.md.twig b/docs/phpdoc-template/index.md.twig
new file mode 100644
index 00000000..2a139b58
--- /dev/null
+++ b/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 %}
diff --git a/docs/phpdoc-template/method.md.twig b/docs/phpdoc-template/method.md.twig
new file mode 100644
index 00000000..e6cefd4b
--- /dev/null
+++ b/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 #}
+
+---
diff --git a/docs/phpdoc-template/template.xml b/docs/phpdoc-template/template.xml
new file mode 100644
index 00000000..67f25900
--- /dev/null
+++ b/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>
diff --git a/docs/phpdoc-template/toc.md.twig b/docs/phpdoc-template/toc.md.twig
new file mode 100644
index 00000000..e18ad1e4
--- /dev/null
+++ b/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 %}