A PHP tool to generate a clean and structured documentation based on PHP documentation, and following Diátaxis documentation framework.
This tool was written for api-platform and is a work in progress.
phive install php-documentation-generator/php-documentation-generator
git clone [email protected]:php-documentation-generator/php-documentation-generator
cd php-documentation-generator
composer install
To create an API reference of a PHP source code directory:
PDG_AUTOLOAD=vendor/autoload.php ./bin/pdg references src docs
Or for a single PHP file:
PDG_AUTOLOAD=vendor/autoload.php ./bin/pdg reference src/Foo.php > Foo.mdx
To generate a guide from a PHP file use the bin/pdg guide command.
There's also an adapted version of phpunit to run a guide tests with bin/pdg-phpunit.
Example of API Platform's configuration:
pdg:
guides:
base_url: '/docs/guide'
output: '/data/docs/guides'
src: './guides'
references:
base_url: '/docs/reference'
exclude: ['*Factory.php', '*.tpl.php']
exclude_path: ['JsonSchema/Tests', 'Metadata/Tests', 'OpenApi/Tests']
namespace: 'ApiPlatform'
output: '/data/docs/reference'
src: '../src'
tags_to_ignore: ['@experimental', '@internal']
Find also a programmatic usage on API Platform's website
This tool is not ready to be customized or used as-is and you'll need to code to adapt to your needs. The code architecture is based on extending Reflection with advanced types (read from php documentation) and Linking support. Feel free to reuse this nice basis to help with your documentation. Templates are written in old-school, hard to read PHP and only output MDX as needed for API Platform. We don't guarantee any backward compatibility release yet.
There are 2 binaries, pdg and pdg-phpunit:
./tools/box compile
gpg -u [email protected] --detach-sign --output bin/pdg.phar.asc bin/pdg.phar
./tools/box compile -c box-phpunit.json.dist
gpg -u [email protected] --detach-sign --output bin/pdg-phpunit.phar.asc bin/pdg-phpunit.phar
These need optimization imo.