Add api documentation generation via phpdocumentor

.phive/phars.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phive xmlns="https://phar.io/phive">
+  <phar name="phpdocumentor" version="^3.4.3" installed="3.4.3" location="./tools/phpdocumentor" copy="false"/>
+</phive>

.phpdoc/template/api-md/class.api-md.twig

@@ -0,0 +1,57 @@
+{% import "include/macros.twig" as macros %}
+{% block content %}
+---
+title: {{ node.FullyQualifiedStructuralElementName }}
+{% include 'config/frontmatter.twig' %}
+---
+
+# {{ node.name }}
+
+{{ node.summary|raw }}
+
+{{ node.description|raw }}
+`{{ macros.mdEndpointName(node.FullyQualifiedStructuralElementName) }}`
+{% if node.deprecated %}* **Warning:** this class is **deprecated**. This means that this class will likely be removed in a future version.
+{% endif %}
+
+{% if node.tags.see is not empty or node.tags.link is not empty %}
+**See Also:**
+
+{% for see in node.tags.see %}
+* {{ see.reference }} {% if see.description %}- {{ see.description|raw }}{% endif %}
+{% endfor %}
+
+{% for link in node.tags.link %}
+* {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description|raw }}{% endif %}
+{% endfor %}
+
+{% endif %}{# node.tags.see || node.tags.link #}
+
+{# Check methods #}
+{% if node.methods|length > 0 %}
+## Available Methods
+{% for method in node.methods %}
+{% if  method.tags.api|length > 0 %}
+### `{{ macros.mdEndpointName(node.FullyQualifiedStructuralElementName, method.name) }}`
+
+{{ method.summary|raw }}
+
+{# Method signature #}
+```curl
+{
+    "method": "{{ macros.mdEndpointName(node.FullyQualifiedStructuralElementName, method.name) }}",
+    "jsonrpc": "2.0",
+    "id": 1,
+    "params": {
+{% for argument in method.arguments %}
+        "{{ argument.name }}": {{ argument.type ? argument.type|raw }},{{ "\n" }}
+{%- endfor %}
+    }
+}
+```
+{% include 'method.api-md.twig' %}
+{% endif %}{# if api tag #}
+{% endfor %}
+{% endif %}{# if methods #}
+
+{% endblock %}

.phpdoc/template/api-md/config/footer.md.twig

@@ -0,0 +1,3 @@
+{# This and it will be added to every .md file at the end #}
+---
+> Automatically generated from source code comments on {{ "now"|date("Y-m-d") }} using [phpDocumentor](http://www.phpdoc.org/)

.phpdoc/template/api-md/config/frontmatter.twig

@@ -0,0 +1,2 @@
+{# This will be added to every .md file in frontmatter section #}
+footer: false

.phpdoc/template/api-md/endpoint.api-md.twig

@@ -0,0 +1 @@
+

.phpdoc/template/api-md/include/macros.twig

@@ -0,0 +1,59 @@
+{#
+  Twig implementation of getRelativePath
+#}
+
+{% macro mdGetRelativePath(_from, _to) %}
+{% set from = _from|split('/') %}
+{% set to = _to|split('/') %}
+{% set relPath = to %}
+{% set break = false %}
+{% for dir in from %}
+{% if not break %}
+{% set depth = loop.index0 %}
+{% if dir == to[depth] %}
+{% set relPath = relPath | slice(1) %}
+{% else %}
+{% set remaining = from|length - depth %}
+{% if remaining > 1 %}
+{% set relPathLen = relPath | length %}
+{% set padLength = remaining - 1 %}
+{% for i in 1..padLength %}
+{% set relPath = '..'|split('/')|merge(relPath) %}
+{% endfor %}
+{% set break = true %}
+{% else %}
+{% set relPath0 = 'api/' ~ relPath[0] %}
+{% set relPathRest = relPath | slice(1) %}
+{% set relPath = relPath0|split('/')|merge(relPathRest) %}
+{% endif %}
+{% endif %}
+{% endif %}
+{% endfor %}
+{{ relPath | join('/') }}{% endmacro %}
+
+{#
+ Get full md link for node with baseDir
+#}
+{% macro mdNodePath(node) %}
+{{ node.FullyQualifiedStructuralElementName | replace({'\\':'/'}) | trim }}.md{% endmacro %}
+
+{#
+  Get full link to class
+#}
+{% macro mdClassPath(node) %}
+{{ 'classes' ~ _self.mdNodePath(node) | trim}}{% endmacro %}
+
+{#
+Create MD link to class node from path
+#}
+{% macro mdClassLink(node, from, name = null) %}
+[{{ name | default(node.name) }}]({{ _self.mdGetRelativePath(from, _self.mdClassPath(node))}}){% endmacro %}
+
+
+{% macro getRpcNamespace(element) %}
+{{ element|replace({"\\": "."})|replace({".Leantime.Domain.": "leantime.rpc."})|replace({".Services": ""}) }}{% endmacro %}
+
+{# Create full endpoint name #}
+{% macro mdEndpointName(parentClass, method) %}
+{{ _self.getRpcNamespace(parentClass) }}.{{ method }}{% endmacro %}
+

.phpdoc/template/api-md/index.api-md.twig

@@ -0,0 +1,37 @@
+{% import "include/macros.twig" as macros %}
+{% block content %}
+---
+title: {{project.name}}
+{% include 'config/frontmatter.twig' %}
+---
+
+# {{ project.name|raw }}
+
+For an introduction into connecting to the Leantime API please see [Api Usage](https://docs.leantime.io/#/api/usage)
+
+RPC Methods are the primary endpoint definition and follow the structure
+`leantime.rpc`.`Module`.`Service`.`Method`
+
+If `Module` and `Service` have the same name they can be summarized to `leantime.rpc`.`servicee`.`method`
+
+## jsonRPC method namespaces
+
+{% for namespace in project.indexes.namespaces|sort((a,b) => a.FullyQualifiedStructuralElementName <=> b.FullyQualifiedStructuralElementName) %}
+{% if namespace.classes|length > 0%}
+
+### Module: `{{ namespace.FullyQualifiedStructuralElementName|replace({"\\": "."})|replace({".Leantime.Domain.": "leantime.rpc."})|replace({".Services": ""}) }}`
+
+{% if namespace.classes|length > 0 %}
+
+| Available Services | Description |
+|---    |---          |
+{% for class in namespace.classes|sort((a,b) => a.FullyQualifiedStructuralElementName <=> b.FullyQualifiedStructuralElementName) %}
+| {{ macros.mdClassLink(class) }} | {{ class.summary|replace({'|': '&#124;'})|nl2br|replace({"\n": "", "\r": "", "\t": ""})|raw }}|
+{% endfor %}{# for class #}
+{% endif %}{# if classes.length #}
+{% endif %}{# if classes, traits, interfaces length #}
+{% endfor %}{# for namespace #}
+
+{% include 'config/footer.md.twig' %}
+{% endblock %}
+

.phpdoc/template/api-md/method.api-md.twig

@@ -0,0 +1,52 @@
+
+
+{{ method.description|raw }}
+
+{% if method.static %}* This method is **static**.{% endif %}
+
+{% if method.abstract %}* This method is **abstract**.{% endif %}
+
+{% if method.final %}* This method is **final**.{% 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.type ? argument.type|raw }}** | {{ argument.description|replace({'|': '|'})|nl2br|replace({"\n": "", "\r": "", "\t": ""})|raw }} |
+{% endfor %}
+
+{% endif %}{# method.arguments is not empty #}
+
+{% if method.response.description %}
+**Returns:**
+{{ method.response.description|raw }}
+```curl
+{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {{ method.response.type|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 #}
+
+---

.phpdoc/template/api-md/template.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<template>
+  <name>api-md</name>
+  <version>1.0.0</version>
+  <transformations>
+    <transformation writer="twig" source="index.api-md.twig" artifact="README.md"/>
+    <transformation writer="twig" query="indexes.classes" source="class.api-md.twig" artifact="classes/{{FullyQualifiedStructuralElementName}}.md"/>
+  </transformations>
+    <parameters>
+    <parameter key="twig-debug">true</parameter>
+  </parameters>
+</template>

.phpdoc/template/md/endpoint.md.twig

@@ -0,0 +1 @@
+