saggre/phpdocumentor-markdown

Generate Markdown documentation from PHP code

phpDocumentor - Generate GitHub/GitLab-Ready Markdown Documentation

Markdown template for phpDocumentor 3.x

Have you ever wished there was an easier way to generate documentation for your PHP source code? Well, now there is! With phpDocumentor and phpDocumentor-markdown, you can automatically generate GitHub/GitLab-ready Markdown documentation from your PHP source code. This template can be used to document 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 [email protected]: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

• Use PSR-12 coding style
• Twig extensions do not yet work with phpDocumentor3 (See #3041), 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

phpdocumentor-markdown's Issues

Interface implementations don't have a link to the implemented interface

Interface implementations don't have a link to the implemented interface

Internal links

Suggestion: For internal links, remove the .md appendix in order to provide compatibility with Wiki pages. Current template opens raw md files instead of rendering it.

No automated testing with GitHub Actions

No automated testing with GitHub Actions

Markdown file sources are not readable due to many line breaks

Missing tests for most macros in themes/markdown/include/macros.twig

Missing tests for most macros in themes/markdown/include/macros.twig

Error in creating links to parent interfaces

When I tried to create documentation for this interface:

<?php
/**
 * Файл с интерфейсом
 * события для `Selsyn`
 *
 * PHP version 8
 *
 * @category Event
 * @package  Selsyn
 * @author   Whatis <[email protected]>
 * @license  unlicense
 * @link     https://github.com/TheWhatis/Selsyn
 */

namespace Whatis\Selsyn\Event;

use Psr\EventDispatcher\StoppableEventInterface;

/**
 * Интерфейс для `Selsyn`
 *
 * PHP version 8
 *
 * @category Event
 * @package  Selsyn
 * @author   Whatis <[email protected]>
 * @license  unlicense
 * @link     https://github.com/TheWhatis/Selsyn
 */
interface IEvent extends StoppableEventInterface
{
    /**
     * Получить название события
     *
     * @return string
     */
    public static function getName(): string;
}

I got an error: strtr(): Argument #1 ($string) must be of type string, phpDocumentor\Descriptor\Collection given.

There was no time to wait until you read and correct (if you correct at all), so I myself found where the problem is.
I replaced this in the file interface.md.twig:

{% if node.parent and node.parent is not empty %}* Parent interface: {{ macros.mdClassLink(node.parent, macros.mdClassPath(node), node.parent.FullyQualifiedStructuralElementName) }}
{% endif %}

For this:

{% if node.parent and node.parent is not empty %}
* Parent interfaces: {% for parent in node.parent %}{% if loop.index0 > 0 %}{{ ', ' }}{% endif %}{{ macros.mdClassLink(parent, macros.mdClassPath(node), parent.FullyQualifiedStructuralElementName) }}{% endfor %}
{% endif %}

I would be grateful if you correct)

Markdown files don't have a link back to home or to an upper level file

Markdown files don't have a link back to home or to an upper level file

Interfaces and parent classes outside project scope have links

Github wiki Markdown dir structure is flat / not nested

Correct url:
https://github.com/Saggre/phpDocumentor-markdown/wiki/AbstractProduct

Generated url (0.1.3):
https://github.com/Saggre/phpDocumentor-markdown/wiki/classes/PhpDocumentorMarkdown/Example/AbstractProduct.md

Fix: Add GitLab and GitHub targets, which generate urls accordingly.

Missing end-to-end tests