Markdown template for phpDocumentor 3.x

Automatically generate GitHub/GitLab-ready Markdown documentation from your PHP source code using phpDocumentor. Generates documentation for classes, interfaces, traits, constants, properties and methods.

Example

An example is available in the example directory.

Installation & Usage

• Please refer to this guide for instructions on installing phpDocumentor.
• Usage instructions assume that phpDocumentor is the phpDocumentor 3.x binary.

Running manually

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

Using Composer

Installation via Composer

# Require this package. You probably want it as a dev dependency
composer require --dev saggre/phpdocumentor-markdown

Running manually after installing via Composer

# Run phpDocumentor with --template argument pointed to markdown template inside vendor directory
phpDocumentor --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 create-docs to generate the documentation.

"scripts": {
    "create-docs": "phpDocumentor --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 phpDocumentor 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 tests

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

# Go to the cloned repository
cd phpDocumentor-markdown

# Install dependencies
composer install

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

# Run PHPUnit in project root directory
composer run-tests

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