Merge pull request #55 from ConvertKit/phpdocumentor

Add phpDocumentor generated PHP SDK Documentation

Author: n7studios

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

@@ -0,0 +1,71 @@
+{% block content %}
+# {{ node.name }}
+
+{% if node.summary %}{{ node.summary|raw }}{% endif %}
+{% if node.description %}{{ node.description|raw }}{% endif %}
+
+* Full name: `{{ node.FullyQualifiedStructuralElementName }}`
+{% if node.parent and node.parent is not empty %}* Parent class: {{ macros.mdClassLink(node.parent, macros.mdClassPath(node), node.parent.FullyQualifiedStructuralElementName) }}
+{% endif %}
+{% if node.final %}* This class is marked as **final** and can't be subclassed
+{% endif %}
+{% if node.deprecated %}* **Warning:** this class is **deprecated**. This means that this class will likely be removed in a future version.
+{% endif %}
+{% if node.interfaces is not empty %}
+* This class implements:
+{% for interface in node.interfaces %}
+{% if loop.index0 > 0 %}{{ ', ' }}{% endif %}{{ macros.mdClassLink(interface, macros.mdClassPath(node), interface) }}{% endfor %}
+
+{% endif %}
+{% if node.abstract %}* This class is an **Abstract class**
+{% endif %}
+{% if node.final %}* This class is a **Final class**
+{% 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 #}
+{% if node.constants | length > 0 %}
+## Constants
+
+| Constant | Visibility | Type | Value |
+|:---------|:-----------|:-----|:------|
+{% for constant in node.constants %}
+|`{{constant.name}}`|{{ constant.visibility | default('*default*') }}|{{constant.type | default(' ')}}|{{constant.value}}|
+{% endfor %}
+{% endif %}
+{% if node.properties | length > 0 %}
+## Properties
+
+{% for property in node.properties %}
+{% include 'property.md.twig' %}
+{% endfor %}
+{% endif %}
+{% if node.methods|length > 0 %}
+## Methods
+
+{% for method in node.methods %}
+{% include 'method.md.twig' %}
+{% endfor %}
+{% endif %}{# if methods #}
+
+{% if node.InheritedMethods|length > 0 %}
+## Inherited methods
+
+{% for method in node.InheritedMethods %}
+{% include 'method.md.twig' %}
+{% endfor %}
+
+{% endif %}{# if InheritedMethods #}
+
+{% endblock %}

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

@@ -0,0 +1,50 @@
+### {{ method.name }}
+
+{{ method.summary | raw }}
+
+{# Method signature #}
+```php
+{% if method.final %}{{ 'final' ~ ' ' }}{% endif %}{{ method.visibility ~ ' ' }}{%if method.static%}{{ 'static' ~ ' ' }}{% endif %}{{ method.name }}({% for argument in method.arguments %}
+{{- argument.type | raw }} 
+{{- argument.byReference ? '&' }} $
+{{- argument.name | raw }}{% if argument.default %} = {{ argument.default | raw }}{% endif %}
+{%- if not loop.last %}, {% endif %}
+{%- endfor %}): {{ method.response.type | raw }}
+```
+{% if method.description %}{{ method.description | raw }}{% endif %}
+{% 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 | default(' ') | replace({'|': '\\|'}) | raw }}** | {{ argument.description | replace({'|': '\\|'}) | nl2br | replace({"\n": "", "\r": "", "\t": ""}) | raw }} |
+{% endfor %}
+{% endif %}{# method.arguments is not empty #}
+{% if method.response.description and method.response.description is not empty %}
+
+**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 is not empty %}- {{ 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 #}
+
+---

.github/phpdoc-template/property.md.twig

@@ -0,0 +1,19 @@
+### {{ property.name }}
+
+{{ property.summary | raw }}
+
+```php
+{{ property.visibility ~ ' ' }}{% if property.static %}{{ 'static' ~ ' ' }}{% endif %}{% if property.type and property.type is not empty %}{{ property.type ~ ' ' }}{% endif %}{{ '$' ~ property.name }}
+```
+
+{% if property.description %}{{ property.description | raw }}{% endif %}
+{% if property.static %}* This property is **static**.{% endif %}
+{% if property.deprecated %}* **Warning:** this property is **deprecated**. This means that this property will likely be removed in a future version.{% endif %}
+{% if property.tags.see is not empty or property.tags.link is not empty %}
+{% for see in property.tags.see %}
+* {{ see.reference }} {% if see.description %}- {{ see.description | raw }}{% endif %}
+{% endfor %}
+{% for link in property.tags.link %}
+* {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description | raw }}{% endif %}
+{% endfor %}
+{% endif %}

.github/phpdoc-template/template.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<template>
+    <name>markdown</name>
+    <author>Sakri Koskimies</author>
+    <email>[email protected]</email>
+    <version>0.0.2</version>
+    <transformations>
+        <transformation writer="twig" query="indexes.classes" source="class.md.twig"
+                        artifact="classes/{{FullyQualifiedStructuralElementName}}.md"/>
+    </transformations>
+    <parameters>
+        <parameter key="twig-debug">true</parameter>
+    </parameters>
+</template>

.gitignore

@@ -1,7 +1,9 @@
+.phpdoc
 .DS_Store
 .env
 .env.testing
 .phpunit.result.cache
+ast.dump
 composer.lock
 phpstan.neon
 src/logs

DEPLOYMENT.md

@@ -16,14 +16,16 @@ We follow [Semantic Versioning](https://semver.org/).
 
 ## Run phpDocumentor
 
-We use [phpDocumentor](https://www.phpdoc.org/) to automatically generate the [PHP SDK documentation](./docs/classes/ConvertKit_API/ConvertKit_API.md).
+We use [phpDocumentor](https://www.phpdoc.org/), with a custom markdown template, to automatically generate the [PHP SDK documentation](./docs/classes/ConvertKit_API/ConvertKit_API.md).
 
 In a Terminal window, run the phpDocumentor command to generate documentation in markdown format:
 
 ```bash
-phpDocumentor --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"
+phpDocumentor --directory=src --target=docs --template=".github/phpdoc-template"
 ```
 
+Markdown is generated using Twig. Changes can be made to the template files in the `.github/phpdoc-template` folder.
+
 ## Commit Changes
 
 Commit the updated files, which should comprise of:

composer.json

@@ -31,5 +31,8 @@
     }
   },
   "minimum-stability": "dev",
-  "prefer-stable": true
-}
+  "prefer-stable": true,
+  "scripts": {
+    "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'"
+  }
+}