Markdown template for phpDocumentor3

Note: Tested with phpDocumentor v3.3.1. Should work with all v3.x releases.

Example

An example is available in the example directory.

Installation & Usage

Usage instructions, assuming phpdoc is the phpDocumentor3 binary.

Using Composer

Installation via Composer

# Require this package
composer require --dev saggre/phpdocumentor-markdown

Running manually after installing via Composer

# Run phpDocumentor with --template argument pointed to markdown template inside vendor directory
phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"

Adding a Composer helper script

Add this script to your composer.json and run composer documentation to generate the documentation.

"scripts": {
    "documentation": "phpdoc --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'"
},

Using with PhpDocumentor XML config

Add a template element to your phpDocumentor XML config and run phpdoc to generate the documentation.

<phpdocumentor>
    <!-- Specify template element inside phpdocumentor -->
    <template name="./vendor/saggre/phpdocumentor-markdown/themes/markdown"/>
</phpdocumentor>

You can also check out the config file used for generating this repository's example documentation for a full example.

Running manually

# Run phpDocumentor with --template argument pointed to this directory's markdown template
phpdoc --directory=src --target=docs --template=<PATH TO THIS REPOSITORY/themes/markdown>

Running tests

# Clone the repository
git clone git@github.com:Saggre/phpDocumentor-markdown.git

# Install dependencies
composer install

# Set up PHPUnit configuration
cp phpunit.xml.dist phpunit.xml

# Run PHPUnit in project root directory
vendor/bin/phpunit

Contributing

• Use PSR-12 coding style
• Twig extensions do not yet work with phpDocumentor3, so custom functionality is created with Twig macros.
• The test suite uses Twig extensions to test the Twig macro functionality.
• Check \phpDocumentor\Descriptor\ProjectDescriptor for data structure used to generate the documentation.

Inspired by:

• dmarkic/phpdoc3-template-md
• cvuorinen/phpdoc-markdown-public
• evert/phpdoc-md
• heimrichhannot/phpdoc-github-template