saggre / phpdocumentor-markdown
Markdown template for phpDocumentor3
Installs: 29 821
Dependents: 21
Suggesters: 0
Security: 0
Stars: 17
Watchers: 2
Forks: 5
Open Issues: 6
Requires (Dev)
- php: >=7.4
- phpunit/phpunit: ^9.5
- twig/twig: 2.*
This package is auto-updated.
Last update: 2024-10-31 00:23:12 UTC
README
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 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
- 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.