Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/saggre/phpdocumentor-markdown
Generate Markdown documentation from PHP code
https://github.com/saggre/phpdocumentor-markdown
documentation github gitlab markdown phpdoc phpdocumentor
Last synced: about 1 month ago
JSON representation
Generate Markdown documentation from PHP code
- Host: GitHub
- URL: https://github.com/saggre/phpdocumentor-markdown
- Owner: Saggre
- License: mit
- Created: 2022-04-14T15:19:52.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-04-01T13:35:11.000Z (8 months ago)
- Last Synced: 2024-09-28T09:04:10.611Z (about 2 months ago)
- Topics: documentation, github, gitlab, markdown, phpdoc, phpdocumentor
- Language: PHP
- Homepage:
- Size: 11.7 MB
- Stars: 16
- Watchers: 2
- Forks: 5
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://www.phpdoc.org/) 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](example/Home.md) directory.
## Installation & Usage
- Please refer to [this guide](https://docs.phpdoc.org/3.0/guide/getting-started/installing.html) for instructions on installing phpDocumentor.
- Usage instructions assume that `phpDocumentor` is the phpDocumentor 3.x binary.
### Running manually
```bash
# Run phpDocumentor with --template argument pointed to this directory's markdown template
phpDocumentor --directory=src --target=docs --template=
```
### Using Composer
#### Installation via Composer
```bash
# Require this package. You probably want it as a dev dependency
composer require --dev saggre/phpdocumentor-markdown
```
#### Running manually after installing via Composer
```bash
# 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.
```json
"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.
```xml
```
You can also check out the [config file](./phpdoc.dist.xml) used for generating this repository's example documentation for a full example.
## Running tests
```bash
# 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](https://github.com/phpDocumentor/phpDocumentor/pull/3041)), so custom functionality is created with [Twig macros](./themes/markdown/include/macros.twig).
- The test suite uses Twig extensions to test the Twig macro functionality.
- Check [`\phpDocumentor\Descriptor\ProjectDescriptor`](https://github.com/phpDocumentor/phpDocumentor/blob/master/src/phpDocumentor/Descriptor/ProjectDescriptor.php) for data structure used to generate the documentation.
## Inspired by:
* [dmarkic/phpdoc3-template-md](https://github.com/dmarkic/phpdoc3-template-md)
* [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)
* [evert/phpdoc-md](https://github.com/evert/phpdoc-md)
* [heimrichhannot/phpdoc-github-template](https://github.com/heimrichhannot/phpdoc-github-template)