├── .gitignore
├── LICENSE
├── README.md
├── composer.json
├── data
    └── templates
    │   └── contao
    │       ├── class.md.twig
    │       ├── index.md.twig
    │       ├── method.md.twig
    │       ├── template.xml
    │       └── toc.md.twig
└── src
    └── Extension
        ├── TwigClassPublicMethods.php
        └── TwigMarkdownAnchorLink.php


/.gitignore:
--------------------------------------------------------------------------------
1 | composer.phar
2 | vendor/
3 | composer.lock
4 | .idea


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 Carl Vuorinen
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 
23 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # phpDocumentor markdown-public template
 2 | 
 3 | [phpDocumentor template](http://www.phpdoc.org/docs/latest/getting-started/changing-the-look-and-feel.html) that generates Markdown documentation of only the public API. It will skip all abstract classes and non-public methods.
 4 | 
 5 | The main use-case for this template is to generate simple and nice looking usage documentation, that can then be published on GitHub.
 6 | 
 7 | For example, a small library can document it's public API in DocBlock comments, use this template to generate the Markdown documentation and then commit it to GitHub with the library to easily create a nice looking documentation for other developers to see.
 8 | 
 9 | Example of documentation generated with this template: https://github.com/cvuorinen/raspicam-php/tree/master/docs
10 | 
11 | ## Installation
12 | 
13 | Install with composer:
14 | 
15 | ```bash
16 | composer require cvuorinen/phpdoc-markdown-public
17 | ```
18 | 
19 | ## Usage
20 | 
21 | Run phpDocumentor and set template as `vendor/cvuorinen/phpdoc-markdown-public/data/templates/markdown-public`.
22 | 
23 | **Example using command-line arguments:**
24 | 
25 | ```bash
26 | ./vendor/bin/phpdoc --directory=src/ --target=docs/ --template="vendor/cvuorinen/phpdoc-markdown-public/data/templates/markdown-public" --title="My Project Documentation"
27 | ```
28 | 
29 | More information about the available arguments can be found at [running phpDocumentor](http://www.phpdoc.org/docs/latest/guides/running-phpdocumentor.html).
30 | 
31 | **Example using configuration file:**
32 | 
33 | Add a file called `phpdoc.xml` with the following content to the root of your project and invoke the `phpdoc` command without arguments. Modify the configuration to suit your project.
34 | 
35 | ```xml
36 | <?xml version="1.0" encoding="UTF-8" ?>
37 | <phpdoc>
38 |     <title>My Project Documentation</title>
39 |     <parser>
40 |         <target>build</target>
41 |     </parser>
42 |     <transformer>
43 |         <target>docs</target>
44 |     </transformer>
45 |     <transformations>
46 |         <template name="vendor/cvuorinen/phpdoc-markdown-public/data/templates/markdown-public" />
47 |     </transformations>
48 |     <files>
49 |         <directory>src</directory>
50 |         <ignore>test/*</ignore>
51 |     </files>
52 | </phpdoc>
53 | ```
54 | 
55 | More information about [configuring phpDocumentor](http://www.phpdoc.org/docs/latest/references/configuration.html).
56 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "heimrichhannot/phpdoc-github-template",
 3 |     "description": "phpDocumentor template that generates Markdown documentation of the public API",
 4 |     "keywords" : [ "PHPDoc", "phpDocumentor", "Documentation", "Markdown" ],
 5 |     "homepage" : "https://github.com/cvuorinen/phpdoc-markdown-public",
 6 |     "license": "MIT",
 7 |     "authors": [
 8 |         {
 9 |             "name": "Carl Vuorinen",
10 |             "email": "carl.vuorinen@gmail.com"
11 |         }
12 |     ],
13 |     "require": {
14 |         "phpdocumentor/phpdocumentor": "~2.8.0"
15 |     },
16 |     "autoload": {
17 |         "psr-4": {
18 |             "Cvuorinen\\PhpdocMarkdownPublic\\": "src"
19 |         }
20 |     }
21 | }
22 | 


--------------------------------------------------------------------------------
/data/templates/contao/class.md.twig:
--------------------------------------------------------------------------------
 1 | ## {{ class.name }}
 2 | 
 3 | {{ class.summary|raw }}
 4 | 
 5 | {{ class.description|raw }}{#
 6 | * Full name: {{ class.FullyQualifiedStructuralElementName }}
 7 | {% if class.parent %}* Parent class: {{ class.parent }}
 8 | {% endif %}
 9 | #}{% if class.interfaces is not empty %} This class implements: {{ class.interfaces|join(', ')|raw }}
10 | {% endif %}{% if class.deprecated %} **Warning:** this class is **deprecated**. This means that this class will likely be removed in a future version.
11 | {% endif %}
12 | 
13 | {% if class.tags.see is not empty or class.tags.link is not empty %}
14 | **See Also:**
15 | 
16 | {% for see in class.tags.see %}
17 | * {{ see.reference }} {% if see.description %}- {{ see.description|raw }}{% endif %}
18 | {% endfor %}
19 | {% for link in class.tags.link %}
20 | * {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description|raw }}{% endif %}
21 | {% endfor %}
22 | 
23 | {% endif %}{# class.tags.see || class.tags.link #}
24 | 
25 | {#
26 | {% for method in publicMethods(class) %}
27 | {% include 'method.md.twig' %}
28 | {% endfor %}
29 | #}


--------------------------------------------------------------------------------
/data/templates/contao/index.md.twig:
--------------------------------------------------------------------------------
 1 | ## API
 2 | 
 3 | {% include 'toc.md.twig' %}
 4 | 
 5 | {% for class in project.indexes.classes|sort_asc %}
 6 | {% if not class.abstract %}
 7 | {% include 'class.md.twig' %}
 8 | {% endif %}
 9 | {% endfor %}
10 | 
11 | 
12 | --------
13 | > This document was automatically generated from source code comments on {{ "now"|date("Y-m-d") }} using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)
14 | 


--------------------------------------------------------------------------------
/data/templates/contao/method.md.twig:
--------------------------------------------------------------------------------
 1 | {# ### {{ method.name }}
 2 | #}
 3 | 
 4 | {# Method signature #}
 5 | ```php
 6 | {{ class.name }}::{{ method.name }}( {% for argument in method.arguments %}
 7 | {{- argument.types ? argument.types|join('|')~' ' }}
 8 | {{- argument.byReference ? '&' }}
 9 | {{- argument.name }}{{ argument.default ? ' = '~argument.default }}
10 | {%- if not loop.last %}, {% endif %}
11 | {%- endfor %} )
12 | {{- method.response.types ? ': '~method.response.types|join('|') }}
13 | ```
14 | {{ method.summary|raw }}
15 | 
16 | {{ method.description|raw }}
17 | 
18 | {#{% if method.static %}* This method is **static**.{% endif %} #}
19 | {% if method.deprecated %} **Warning:** this method is **deprecated**. This means that this method will likely be removed in a future version.
20 | {% endif %}
21 | 
22 | {% if method.arguments is not empty %}
23 | 
24 | | Parameter | Type | Description |
25 | |-----------|------|-------------|
26 | {% for argument in method.arguments %}
27 | | `{{ argument.name }}` | **{{ argument.types ? argument.types|join('&#124;')|raw }}** | {{ argument.description|replace({'|': '&#124;'})|raw }} |
28 | {% endfor %}
29 | 
30 | {% endif %}{# method.arguments is not empty #}
31 | 
32 | {% if method.response.description %}
33 | 
34 | **returns** {{ method.response.description|raw }}
35 | 
36 | {% endif %}
37 | 
38 | {% if method.tags.see is not empty or method.tags.link is not empty %}
39 | **See Also:**
40 | 
41 | {% for see in method.tags.see %}
42 | * {{ see.reference }} {% if see.description %}- {{ see.description|raw }}{% endif %}
43 | {% endfor %}
44 | {% for link in method.tags.link %}
45 | * {{ link.link }} {% if link.description and link.description != link.link %}- {{ link.description|raw }}{% endif %}
46 | {% endfor %}
47 | 
48 | {% endif %}{# method.tags.see || method.tags.link #}
49 | 
50 | ---
51 | 
52 | 


--------------------------------------------------------------------------------
/data/templates/contao/template.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="utf-8"?>
 2 | <template>
 3 |   <author>Carl Vuorinen</author>
 4 |   <email>carl.vuorinen@gmail.com</email>
 5 |   <version>1.0.0</version>
 6 |   <copyright>Carl Vuorinen 2015</copyright>
 7 |   <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>
 8 |   <transformations>
 9 |     <transformation writer="twig" source="templates/contao/index.md.twig" artifact="README.md" />
10 |   </transformations>
11 |   <parameters>
12 |     <!--<parameter key="twig-debug">true</parameter>-->
13 |     <parameter key="twig-extension">Cvuorinen\PhpdocMarkdownPublic\Extension\TwigMarkdownAnchorLink</parameter>
14 |     <parameter key="twig-extension">Cvuorinen\PhpdocMarkdownPublic\Extension\TwigClassPublicMethods</parameter>
15 |   </parameters>
16 | </template>
17 | 


--------------------------------------------------------------------------------
/data/templates/contao/toc.md.twig:
--------------------------------------------------------------------------------
 1 | ## Classes
 2 | 
 3 | {% for class in project.indexes.classes|sort_asc %}
 4 | {% if not class.abstract %}
 5 | * {{ class.name }} - {{ class.summary|raw }}
 6 | 	{#* {{ anchorLink(class.name) }} - {{ class.summary|raw }}
 7 | 	 {% for method in publicMethods(class) %}
 8 | 		* {{ anchorLink(method.name) }}
 9 | 	{% endfor %} #}
10 | {% endif %}
11 | {% endfor %}
12 | 


--------------------------------------------------------------------------------
/src/Extension/TwigClassPublicMethods.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Cvuorinen\PhpdocMarkdownPublic\Extension;
 4 | 
 5 | use phpDocumentor\Descriptor\ClassDescriptor;
 6 | use phpDocumentor\Descriptor\MethodDescriptor;
 7 | use Twig_Extension;
 8 | use Twig_SimpleFunction;
 9 | 
10 | /**
11 |  * Twig extension to get only the public methods from a \phpDocumentor\Descriptor\ClassDescriptor instance.
12 |  *
13 |  * Adds the following function to Twig:
14 |  *
15 |  *  publicMethods(ClassDescriptor class): MethodDescriptor[]
16 |  */
17 | class TwigClassPublicMethods extends Twig_Extension
18 | {
19 |     const NAME = 'TwigClassPublicMethods';
20 | 
21 |     /**
22 |      * {@inheritdoc}
23 |      */
24 |     public function getName()
25 |     {
26 |         return self::NAME;
27 |     }
28 | 
29 |     /**
30 |      * {@inheritdoc}
31 |      */
32 |     public function getFunctions()
33 |     {
34 |         return array(
35 |             new Twig_SimpleFunction('publicMethods', array($this, 'getPublicMethods'))
36 |         );
37 |     }
38 | 
39 |     /**
40 |      * @param ClassDescriptor $class
41 |      *
42 |      * @return MethodDescriptor[]
43 |      */
44 |     public function getPublicMethods($class)
45 |     {
46 |         if (!$class instanceof ClassDescriptor) {
47 |             return [];
48 |         }
49 | 
50 |         $methods = $class->getMagicMethods()
51 |             ->merge($class->getInheritedMethods())
52 |             ->merge($class->getMethods());
53 | 
54 |         return array_filter(
55 |             $methods->getAll(),
56 |             function (MethodDescriptor $method) {
57 |                 return $method->getVisibility() === 'public';
58 |             }
59 |         );
60 |     }
61 | }
62 | 


--------------------------------------------------------------------------------
/src/Extension/TwigMarkdownAnchorLink.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Cvuorinen\PhpdocMarkdownPublic\Extension;
 4 | 
 5 | use Twig_Extension;
 6 | use Twig_SimpleFunction;
 7 | 
 8 | /**
 9 |  * Twig extension to create Markdown anchor links (within a single page).
10 |  *
11 |  * Links need to be created in the same order as the anchors appear in the document, so that links with
12 |  * same title will be correctly suffixed with a numeric index.
13 |  *
14 |  * Adds the following function:
15 |  *
16 |  *  anchorLink(string title): string
17 |  */
18 | class TwigMarkdownAnchorLink extends Twig_Extension
19 | {
20 |     const NAME = 'TwigMarkdownAnchorLink';
21 | 
22 |     /**
23 |      * Keep track of the created links so we can check if a link with the same title already exists.
24 |      *
25 |      * @var array
26 |      */
27 |     private static $links = array();
28 | 
29 |     /**
30 |      * {@inheritdoc}
31 |      */
32 |     public function getName()
33 |     {
34 |         return self::NAME;
35 |     }
36 | 
37 |     /**
38 |      * {@inheritdoc}
39 |      */
40 |     public function getFunctions()
41 |     {
42 |         return array(
43 |             new Twig_SimpleFunction('anchorLink', array($this, 'createAnchorLink'))
44 |         );
45 |     }
46 | 
47 |     /**
48 |      * @param string $title
49 |      *
50 |      * @return string
51 |      */
52 |     public function createAnchorLink($title)
53 |     {
54 |         $anchor = strtolower($title);
55 | 
56 |         // Check if we already have link to an anchor with the same name, and add count suffix
57 |         $linkCounts = array_count_values(self::$links);
58 |         $anchorSuffix = array_key_exists($anchor, $linkCounts)
59 |             ? '-' . $linkCounts[$anchor] : '';
60 |         array_push(self::$links, $anchor);
61 | 
62 |         return sprintf("[%s](%s)", $title, '#' . $anchor . $anchorSuffix);
63 |     }
64 | }
65 | 


--------------------------------------------------------------------------------