README

Use cases: In-repository documentation, GitHub/GitLab wikis, AI prompt context.

Markdown template for phpDocumentor3

Wish there was an easy way to generate PHP source code documentation?
Using phpDocumentor with phpDocumentor-markdown template, you can automatically generate GitHub/GitLab-ready Markdown documentation from PHP source code.

This template can be used to document:

Example

Examples are available in the .wiki directory.

Installation & Usage

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

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>

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
phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"

Installation & Usage tips

Adding a Composer helper script

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

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

GitLab wiki

The output of this template can be used directly as a GitLab wiki.

GitHub wiki

⚠️ GitHub wiki uses a flat directory structure for linking, so the internal links in the resulting documentation will not work as expected.

CI pipelines

You can use the PhpDocumentor Docker image with this template in your CI pipelines to generate documentation automatically.

AI integration

The generated documentation can be used as prompt context for AI models that work with source code. For other use cases you'll likely want structured data, like JSON.

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 test

Contributing

• There are unit tests and functional tests available in the tests directory.
  • Unit tests are used to test individual Twig macros
  • Functional tests are used to test the whole documentation generation process

Inspired by:

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