README

Introduction

This is a custom template to use with phpDocumentor.

It is intended to create the code documentation as markdown files, fully compatible to serve as a GitHub Wiki in a GitHub repository of your choice.

Example

You can find a live example in this GitHub repository: zorgch/zorg-code/wiki

Installation

1. Via composer composer require linchpin/phpdocumentor-template-markdown
2. Download the latest release

Pre-requisites

• phpDocumentor must be installed or available using its .phar
• You have a GitHub Wiki cloned locally

Generate GitHub Wiki Markdown from your code

1. Specifiy this template phpdocumentor-template-markdown while generating your code documentation using phpDocumentor: php ./phpDocumentor.phar -d "/path/to/my/sourcecode" -t "/path/to/local/github-wiki" --template="/vendor/linchpin/phpdocumentor-template-markdown" --cache-folder "/path/to/store/cache" --title "My code project"

• NOTE: you may get an error at the end of the parsing - which you can just ignore, all work was done: ERROR In PathGenerator.php line 120: Variable substitution in path /namespaces/{{name}}.md failed, variable "name" did not return a value

1. The target directory /github-wiki consists of various markdown (.md) files now
2. Review, commit & push your local GitHub Wiki repository changes
3. Browse to the Wiki on the corresponding GitHub repository to see your code documentation online

Result

Consider that GitHub Wiki pages are in a flat file hierarchy. Fortunately you still can use folders in the repository itself - so you can have a clean structure in the Wiki repository, but when linking between files it must behave like all Wiki pages are in a single, flat hierarchy.

Outputted file hierarchy

The output consists of the following files hierarchy:

GitHub Wiki pages handling

As mentioned, due to GitHub Wiki pages behaving not within any hierarchy, linking between Wiki pages is done...

• by referencing the file name of the page
• leaving away the .md extension

So use class-MyClass to link to the file /wiki/classes/class-MyClass.md.

Or file-myconfigs.inc.php to link to the file /wiki/files/file-myconfigs.inc.php.md.